Интеграция с Argo CD

Argo CD — декларативный инструмент для непрерывной доставки в Kubernetes по модели GitOps.

В этом руководстве описана интеграция инстанса Yandex Managed Service for GitLab, кластера Kubernetes и установленного в кластере Argo CD, который выполняет сборку Docker-контейнеров с помощью инструмента Kaniko.

Чтобы интегрировать Argo CD с Managed Service for Kubernetes и Managed Service for GitLab:

1. Создайте ресурсы Managed Service for Kubernetes и Container Registry.
2. Создайте инстанс GitLab.
3. Настройте GitLab.
4. Создайте GitLab Runner.
5. Подготовьте репозиторий приложения для развертывания.
6. Разверните приложение с помощью Argo CD.

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

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

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

• Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.

  По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

• Утилиту потоковой обработки JSON-файлов jq.

• Менеджер пакетов Helm.

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

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

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

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

   Вручную

   С помощью Terraform

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

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

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

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

      Совет

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

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

      • Сервисный аккаунт для ресурсов — созданный ранее сервисный аккаунт с ролью editor.
      • Сервисный аккаунт для узлов — созданный ранее сервисный аккаунт с ролями container-registry.images.puller и container-registry.images.pusher.
      • Версия Kubernetes — 1.21 или выше.
      • Публичный адрес — Автоматически.
      • Отдельные параметры группы узлов:
        • vCPU — 4.
        • RAM — 8 ГБ.
        • Прерываемая.
        • Масштабирование — Автоматическое.
        • Минимальное кол-во узлов — 1.
        • Максимальное кол-во узлов — 4.
        • Начальное кол-во узлов — 1.

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

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

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

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

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

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

      • Сеть.
      • Подсеть.
      • Группа безопасности и правила, необходимые для работы кластера, группы узлов, инстанса Managed Service for GitLab и контейнера Container Registry:
        • Правила для служебного трафика.
        • Правила для доступа к 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 для кластера и групп узлов.
      • CIDR кластера 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:

Создайте 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.

Подготовьте репозиторий приложения для развертывания

1. В Managed Service for GitLab создайте новый репозиторий my-app:

   Инстанс Managed Service for GitLab

   ВМ с образом GitLab

   1. Авторизуйтесь в веб-интерфейсе инстанса Managed Service for GitLab.

   2. Перейдите в группу gitlab-test.

   3. Нажмите кнопку Create a project.

   4. Нажмите кнопку Create blank project.

   5. Заполните поля:

      • Project name — my-app.
      • Project URL — выберите gitlab-test в поле рядом с FQDN инстанса Managed Service for GitLab.

      Остальные поля оставьте без изменений.

   6. Нажмите кнопку Create project.

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

   1. На странице сервиса Yandex Compute Cloud выберите созданную ВМ и найдите ее публичный IP-адрес.
   2. Откройте в браузере ссылку http://<публичный IP-адрес ВМ>. Откроется административная панель GitLab.
   3. Задайте пароль администратора и нажмите кнопку Change your password.
   4. Введите логин root и пароль администратора.
   5. Нажмите кнопку Sign in.
   6. Выберите Create a project.
   7. Задайте имя проекта: my-app.
   8. Нажмите кнопку Create project.

2. Получите авторизованный ключ для созданного ранее сервисного аккаунта с ролью container-registry.images.pusher:

   yc iam key create --service-account-name <имя сервисного аккаунта реестра> -o key.json
   

3. Сохраните содержимое этого ключа — оно потребуется на следующем шаге:

   cat key.json | base64
   

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

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

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

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

      Name	Value	Опции
      CI_REGISTRY	cr.yandex/<идентификатор реестра>	no
      CI_REGISTRY_USER	json_key	no
      CI_REGISTRY_PASSWORD	<вывод команды cat key.json | base64>	Mask variable

5. Настройте доступ к репозиторию:

   1. Сгенерируйте новую пару SSH-ключей или используйте существующую.
   2. Добавьте публичную часть SSH-ключа в настройки учетной записи GitLab.

6. Клонируйте репозиторий:

   git clone git@<имя инстанса Managed Service for GitLab>.gitlab.yandexcloud.net:gitlab-test/my-app.git
   

7. Загрузите архив app.zip и распакуйте его.

8. Скопируйте в директорию my-app все файлы (включая скрытые) из загруженного архива:

   cp -a <путь к директории с файлами из app.zip> <путь к директории my-app>
   

9. Сохраните изменения и отправьте их в репозиторий:

   git add . && \
   git commit -m "Add app src and CI" && \
   git push
   

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

11. Откройте завершенную сборку и скопируйте строку из лога, она понадобится на следующем этапе:

    INFO[0025] Pushing image to cr.yandex/<идентификатор реестра>/gitlab-test/my-app:main.<номер коммита>
    

Разверните приложение с помощью Argo CD

Установите Argo CD в кластер Kubernetes

1. Установите Argo CD согласно инструкции.

2. Настройте переадресацию порта сервиса argocd-server на локальный компьютер и подключитесь к кластеру Kubernetes:

   kubectl port-forward svc/<название приложения Argo CD>-argocd-server 8080:443
   

3. Получите пароль администратора из секрета Kubernetes:

   kubectl get secret argocd-initial-admin-secret \
     -o jsonpath='{.data.password}' | base64 -d
   

4. Откройте в браузере консоль Argo CD по адресу https://127.0.0.1:8080.

5. Авторизуйтесь в консоли, используя имя пользователя admin и пароль, полученный на предыдущем шаге.

Создайте репозиторий GitLab для Argo CD

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

2. Задайте параметры нового токена:

   • Token name — argocd.
   • Select scopes — read_repository.

3. Нажмите кнопку Create project access token.

4. Скопируйте значение созданного токена.

5. В консоли Argo CD перейдите в раздел Settings → Repositories.

6. Нажмите кнопку Connect Repo Using SSH.

7. В открывшейся форме задайте параметры:

   • Repository URL — URL репозитория вида https://<имя инстанса GitLab>.gitlab.yandexcloud.net/gitlab-test/my-app.git.
   • Username — gitlab-ci-token.
   • Password — токен GitLab, сгенерированный ранее.

8. Нажмите кнопку Connect.

9. В консоли Argo CD перейдите в раздел Applications и нажмите кнопку Create Application.

10. В открывшейся форме задайте параметры:

    • Application Name — my-app.
    • Project — default.
    • Sync policy — Automatic, затем выберите опции Prune resources и Self Heal.
    • Sync policy — Auto-Create Namespace.
    • Source — URL репозитория вида https://<имя инстанса GitLab>.gitlab.yandexcloud.net/gitlab-test/my-app.git.
    • Path — .helm.
    • Cluster URL — https://kubernetes.default.svc.
    • Namespace — my-app.
    • Directory — выберите Helm и в появившейся секции Parameters задайте параметры, исходя из значения успешно завершенной сборки GitLab:
      • image.repository — cr.yandex/<идентификатор реестра>/gitlab-test/my-app.
      • image.tag — main.<номер коммита>.

11. Нажмите кнопку Create и дождитесь завершения синхронизации.

12. Для проверки запуска приложения выполните команду в кластере Kubernetes:

    kubectl get all -n my-app
    

Проверьте автоматическую синхронизацию из репозитория

1. Перейдите в директорию с клонированным проектом и откройте файл .helm/values.yaml.

2. Измените значение параметра replicaCount на 3.

3. Сохраните изменения и отправьте их в репозиторий:

   git add . && \
   git commit -m "Increase replica count" && \
   git push
   

4. В консоли Argo CD дождитесь синхронизации приложения.

5. Проверьте, что количество подов приложения в кластере увеличилось:

   kubectl get pod -n my-app
   

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

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

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

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

   Вручную

   С помощью Terraform

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

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

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

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

      terraform validate
      

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

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

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

         terraform plan
         

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

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

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

            terraform apply
            

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

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

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

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