Непрерывное развертывание контейнеризованных приложений с помощью GitLab

GitLab — инструмент непрерывной интеграции (Continuous integration, CI).

В этом руководстве описаны:

• Сборка приложения в Docker-контейнер.
• Развертывание приложения из контейнера в кластере Yandex Managed Service for Kubernetes через GitLab с помощью инструментов Yandex Cloud.

После каждого коммита в GitLab:

• Выполнится сценарий, в котором описаны шаги сборки Docker-образа.
• Применится новая конфигурация кластера Managed Service for Kubernetes, в которой будет указано приложение для развертывания.

Чтобы настроить необходимую инфраструктуру для хранения исходного кода, сборки Docker-образа и развертывания приложения:

1. Подготовьте облако к работе.

   1. Изучите список необходимых платных ресурсов.

   2. Установите дополнительные зависимости.

2. Создайте ресурсы Managed Service for Kubernetes и Yandex Container Registry.

3. Создайте инстанс GitLab.

4. Настройте GitLab.

5. Создайте тестовое приложение.

6. Создайте GitLab Runner.

7. Настройте сборку и развертывание Docker-образа из CI.

Если созданные ресурсы больше не нужны, удалите их.

Подготовьте облако к работе

Перед работой нужно зарегистрироваться в Yandex Cloud и создать платежный аккаунт:

1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь, если вы еще не зарегистрированы.
2. На странице биллинга убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

Необходимые платные ресурсы

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

• Диски и постоянно запущенные виртуальные машины (см. тарифы Yandex Compute Cloud).
• Использование динамического публичного IP-адреса (см. тарифы Yandex Virtual Private Cloud).
• Хранение созданных Docker-образов (см. тарифы Container Registry).
• Использование мастера Managed Service for Kubernetes (см. тарифы Managed Service for Kubernetes).

Установите дополнительные зависимости

Для выполнения сценария установите в локальном окружении:

• Интерфейс командной строки Yandex Cloud (YC CLI).
• Утилиту потоковой обработки JSON-файлов jq.
• Менеджер пакетов Helm.

Создайте ресурсы Managed Service for Kubernetes и Container Registry

1. Создайте кластер Managed Service for Kubernetes и реестр Container Registry.

   Для выполнения сценария создайте ресурсы Managed Service for Kubernetes: кластер и группу узлов.

   Для хранения Docker-образов вам понадобится реестр Container Registry.

   Вручную

   С помощью Terraform

   1. Если у вас еще нет сети, создайте ее.

   2. Если у вас еще нет подсетей, создайте их в зонах доступности, где будут созданы кластер Managed Service for Kubernetes и группа узлов.

   3. Создайте сервисные аккаунты:

      • С ролью editor на каталог, в котором создается кластер Managed Service for Kubernetes. От его имени будут создаваться ресурсы, необходимые кластеру Managed Service for Kubernetes.
      • С ролями container-registry.images.puller и container-registry.images.pusher. От его имени узлы будут загружать в реестр собранные в GitLab Docker-образы, а также скачивать их для запуска подов.

      Совет

      Вы можете использовать один и тот же сервисный аккаунт для управления кластером Managed Service for Kubernetes и его группами узлов.

   4. Создайте кластер Managed Service for Kubernetes и группу узлов со следующими настройками:

      • Сервисный аккаунт для ресурсов — созданный ранее сервисный аккаунт с ролью editor.
      • Сервисный аккаунт для узлов — созданный ранее сервисный аккаунт с ролями container-registry.images.puller и container-registry.images.pusher.
      • Версия Kubernetes — не ниже 1.21.
      • Публичный адрес — Автоматически.

      Сохраните идентификатор кластера — он понадобится для следующих шагов.

   5. Создайте реестр.

   6. Сохраните идентификатор созданного реестра — он понадобится для следующих шагов.

   1. Если у вас еще нет Terraform, установите его.

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

   3. Скачайте в ту же рабочую директорию файл конфигурации кластера k8s-gl.tf. В файле описаны:

      • Сеть.
      • Подсеть.
      • Группа безопасности и правила, необходимые для работы кластера Managed Service for Kubernetes:
        • Правила для служебного трафика.
        • Правила для доступа к API Kubernetes и управления кластером с помощью kubectl через порты 443 и 6443.
        • Правила для подключения к Git-репозиторию по протоколу SSH через порт 22.
        • Правила, разрешающие HTTP- и HTTPS-трафик через порты 80 и 443.
        • Правила для подключения к Container Registry через порт 5050.
      • Кластер Managed Service for Kubernetes.
      • Сервисный аккаунт, необходимый для работы кластера и группы узлов Managed Service for Kubernetes.
      • Реестр Container Registry.

   4. Укажите в файле конфигурации:

      • Идентификатор каталога.
      • Версию Kubernetes для кластера и групп узлов Managed Service for Kubernetes.
      • CIDR кластера Managed Service for Kubernetes.
      • Имя сервисного аккаунта кластера.
      • Имя реестра Container Registry.

   5. Выполните команду terraform init в директории с конфигурационными файлами. Эта команда инициализирует провайдер, указанный в конфигурационных файлах, и позволяет работать с ресурсами и источниками данных провайдера.

   6. Проверьте корректность файлов конфигурации Terraform с помощью команды:

      terraform validate
      

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

   7. Создайте необходимую инфраструктуру:

      1. Выполните команду для просмотра планируемых изменений:

         terraform plan
         

         Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

      2. Если вас устраивают планируемые изменения, внесите их:

         1. Выполните команду:

            terraform apply
            

         2. Подтвердите изменение ресурсов.

         3. Дождитесь завершения операции.

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

2. Установите kubectl и настройте его на работу с созданным кластером.

Получите токен сервисного аккаунта Kubernetes для аутентификации в GitLab

Чтобы получить токен сервисного аккаунта Kubernetes:

1. Настройте локальное окружение на работу с созданным кластером Kubernetes:

   yc managed-kubernetes cluster get-credentials <идентификатор или имя кластера> --external
   

2. Сохраните спецификацию для создания сервисного аккаунта Kubernetes в YAML-файл gitlab-admin-service-account.yaml:

   gitlab-admin-service-account.yaml

   ---
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: gitlab-admin
     namespace: kube-system
   ---
   apiVersion: rbac.authorization.k8s.io/v1beta1
   kind: ClusterRoleBinding
   metadata:
     name: gitlab-admin
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: cluster-admin
   subjects:
   - kind: ServiceAccount
     name: gitlab-admin
     namespace: kube-system
   

3. Создайте сервисный аккаунт:

   kubectl apply -f gitlab-admin-service-account.yaml
   

4. Узнайте токен сервисного аккаунта:

   kubectl -n kube-system get secrets -o json | \
   jq -r '.items[] | select(.metadata.name | startswith("gitlab-admin")) | .data.token' | \
   base64 --decode
   

5. Сохраните полученный токен — он понадобится для следующих шагов.

Создайте инстанс GitLab

Настройте GitLab

Чтобы настроить GitLab и подготовить процесс непрерывной интеграции (Continuous Integration, CI), создайте новый проект и введите параметры для авторизации в CI:

Создайте тестовое приложение

Создайте тестовое приложение, которое можно будет развернуть в кластере Managed Service for Kubernetes:

1. Добавьте в проект Dockerfile:

   1. Авторизуйтесь в GitLab.

   2. На главной странице выберите репозиторий.

   3. Выберите раздел Repository → Files.

   4. Нажмите кнопку + и в выпадающем меню выберите пункт New file.

   5. Назовите файл Dockerfile и добавьте в него код:

      FROM alpine:3.10
      CMD echo "Hello"
      

   6. Напишите комментарий к коммиту в поле Commit message: Dockerfile for test application.

   7. Нажмите кнопку Commit changes.

2. Добавьте в проект манифест ресурсов кластера Managed Service for Kubernetes:

   1. Выберите раздел Repository → Files.

   2. Нажмите кнопку + и в выпадающем меню выберите пункт New file.

   3. Назовите файл k8s.yaml:

      apiVersion: v1
      kind: Namespace
      metadata:
        name: hello-world
      ---
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: hello-world-deployment
        namespace: hello-world
      spec:
        replicas: 1
        selector:
          matchLabels:
            app: hello
        template:
          metadata:
            namespace: hello-world
            labels:
              app: hello
          spec:
            containers:
              - name: hello-world
                image: cr.yandex/<идентификатор реестра>/hello:__VERSION__
                imagePullPolicy: Always
      

   4. В поле <идентификатор реестра> укажите идентификатор созданного ранее реестра.

   5. Напишите комментарий к коммиту в поле Commit message: Docker image deployment config.

   6. Нажмите кнопку Commit changes.

Создайте GitLab Runner

Чтобы запускать задачи сборки в кластере Yandex Managed Service for Kubernetes, создайте GitLab Runner.

1. Подключите Helm-репозиторий, который содержит дистрибутив GitLab Runner:

   helm repo add gitlab https://charts.gitlab.io
   

2. Узнайте настройки GitLab Runner:

   1. Откройте в браузере административную панель GitLab:
      • Если GitLab развернут на виртуальной машине Yandex Compute Cloud, используйте ее публичный IP-адрес.
      • Если GitLab развернут в сервисе Managed Service for GitLab, используйте FQDN инстанса.
   2. Выберите проект с именем gitlab-test.
   3. В открывшемся окне слева нажмите кнопку Settings и выберите пункт CI/CD.
   4. В блоке Runners нажмите кнопку Expand.
   5. Сохраните значения параметров URL и registration token — они понадобятся на следующем шаге.

3. Создайте файл values.yaml, содержащий настройки GitLab Runner:

   values.yaml

   ---
   imagePullPolicy: IfNotPresent
   gitlabUrl: <публичный IP-адрес ВМ или FQDN инстанса Managed Service for GitLab>
   runnerRegistrationToken: "<registration token>"
   terminationGracePeriodSeconds: 3600
   concurrent: 10
   checkInterval: 30
   sessionServer:
    enabled: false
   rbac:
     create: true
     clusterWideAccess: true
     podSecurityPolicy:
       enabled: false
       resourceNames:
         - gitlab-runner
   runners:
     config: |
       [[runners]]
         [runners.kubernetes]
           namespace = "{{.Release.Namespace}}"
           image = "ubuntu:20.04"
           privileged = true
   

4. Установите GitLab Runner с помощью команды:

   helm install --namespace default gitlab-runner -f values.yaml gitlab/gitlab-runner
   

5. Дождитесь перехода пода GitLab Runner в состояние Running:

   kubectl get pods -n default | grep gitlab-runner
   

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

Подробнее про установку и настройку GitLab Runner читайте в документации GitLab.

Настройте сборку и развертывание Docker-образа из CI

1. Создайте переменные окружения GitLab.

   1. На панели слева в GitLab перейдите в раздел Settings и во всплывающем списке выберите пункт CI/CD.

   2. Нажмите кнопку Expand напротив пункта Variables.

   3. Добавьте две переменные окружения:

      • KUBE_URL — адрес мастера Kubernetes. Узнайте его с помощью команды:

        yc managed-kubernetes cluster get <идентификатор или имя кластера Kubernetes> --format=json \
          | jq -r .master.endpoints.external_v4_endpoint
        

      • KUBE_TOKEN — токен, который будет использовать GitLab для применения конфигурации. Используйте токен, полученный ранее.

      Для добавления переменной:

      • Нажмите кнопку Add variable.
      • В появившемся окне в поле Key укажите имя переменной, в поле Value — значение переменной.
      • Нажмите кнопку Add variable.

2. GitLab позволяет настраивать сценарии сборки в YAML-файле. Создайте файл конфигурации .gitlab-ci.yml:

   1. На панели слева в GitLab перейдите в раздел Repository и выберите вкладку Files.

   2. Справа от имени проекта нажмите кнопку + и в выпадающем меню выберите пункт New file.

   3. Назовите файл .gitlab-ci.yml. Добавьте в него шаги сборки и загрузки Docker-образа и обновления конфигурации приложения в кластере Kubernetes:

      stages:
        - build
        - deploy
      
      build:
        stage: build
        variables:
          DOCKER_DRIVER: overlay2
          DOCKER_TLS_CERTDIR: ""
          DOCKER_HOST: tcp://localhost:2375/
        image: cr.yandex/yc/metadata-token-docker-helper:0.2
        services:
          - docker:19.03.1-dind
        script:
          - docker build . -t cr.yandex/<идентификатор реестра>/hello:gitlab-$CI_COMMIT_SHORT_SHA
          - docker push cr.yandex/<идентификатор реестра>/hello:gitlab-$CI_COMMIT_SHORT_SHA
      
      deploy:
        image: gcr.io/cloud-builders/kubectl:latest
        stage: deploy
        script:
          - kubectl config set-cluster k8s --server="$KUBE_URL" --insecure-skip-tls-verify=true
          - kubectl config set-credentials admin --token="$KUBE_TOKEN"
          - kubectl config set-context default --cluster=k8s --user=admin
          - kubectl config use-context default
          - sed -i "s/__VERSION__/gitlab-$CI_COMMIT_SHORT_SHA/" k8s.yaml
          - kubectl apply -f k8s.yaml
      

   4. Замените в приведенном файле <идентификатор реестра> на идентификатор вашего реестра, созданного ранее.

   5. Напишите комментарий к коммиту в поле Commit message: CI scripts.

   6. Нажмите кнопку Commit changes.

   В файле .gitlab-ci.yml описаны два шага сборки проекта:

   • Сборка Docker-образа с использованием Dockerfile из предыдущего этапа и загрузка образа в Yandex Container Registry.
     • Для этого шага используйте контейнер для сборки Docker-образов и запустите Docker-сервер как GitLab-сервис.
     • Для аутентификации в Container Registry используйте сервисный аккаунт, подключенный к узлам Kubernetes. В начале работы этому аккаунту была назначена роль container-registry.images.pusher.
     • Чтобы получить из метаданных виртуальной машины данные для аутентификации, используется вспомогательный публичный Docker-образ cr.yandex/yc/metadata-token-docker-helper:0.2. Внутри него работает Docker credential helper, который получает Identity and Access Management-токен из сервиса метаданных.
   • Настройка окружения для работы с Kubernetes и применение конфигурации k8s.yaml к кластеру Kubernetes. Таким образом приложение развертывается на созданном ранее кластере.

3. После сохранения файла запустится сценарий сборки. Чтобы посмотреть его выполнение, выберите в выпадающем меню пункт CI/CD → Pipelines. Дождитесь успешного завершения обоих этапов сборки.

4. Проверьте результат, посмотрев логи контейнера в кластере Kubernetes:

   kubectl logs deployment/hello-world-deployment -n hello-world
   

   Результат:

   Hello
   

Удалите созданные ресурсы

Если созданные ресурсы вам больше не нужны, удалите их:

1. Удалите созданные Docker-образы.

2. Удалите кластер Managed Service for Kubernetes и реестр Container Registry:

   Вручную

   С помощью Terraform

   1. Удалите кластер Managed Service for Kubernetes.
   2. Удалите реестр Container Registry.
   3. Удалите созданные подсети и сети.
   4. Удалите созданные сервисные аккаунты.

   1. В командной строке перейдите в директорию, в которой расположен актуальный конфигурационный файл Terraform с планом инфраструктуры.

   2. Удалите конфигурационный файл k8s-gl.tf.

   3. Проверьте корректность файлов конфигурации Terraform с помощью команды:

      terraform validate
      

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

   4. Подтвердите изменение ресурсов.

      1. Выполните команду для просмотра планируемых изменений:

         terraform plan
         

         Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

      2. Если вас устраивают планируемые изменения, внесите их:

         1. Выполните команду:

            terraform apply
            

         2. Подтвердите изменение ресурсов.

         3. Дождитесь завершения операции.

      Все ресурсы, которые были описаны в конфигурационном файле k8s-gl.tf, будут удалены.

3. Удалите созданную ВМ GitLab или инстанс Managed Service for GitLab.

См. также

• Создание тестовых ВМ через GitLab CI.