В данной инструкции мы попробуем разобраться с тем, как работать с Terraform. Мы рассмотрим его установку и базовую настройку, немного синтаксиса и примеры работы с облачным провайдером Яндекс.Облако. Инструкция рассчитана на работу с Linux (Deb и RPM).

Регистрация на хостинге

Для работы с хостинг-провайдером нам заранее понадобятся авторизационные данные и идентификаторы ресурсов. Их мы будем прописывать в сценариях terraform.

Нам нужно зарегистрироваться на сервисе Yandex.Cloud (в нашем примере, мы будем работать, именно, с ним). После этого, нам нужно получить:

1. OAuth-токен. Используется в процедуре аутентификации для получения IAM-токена и нужен нам для прохождения авторизации при подключении terraform. Выдается на 1 год. Получить можно, отправив запрос со страницы документации Яндекс.

2. Идентификатор облака. После регистрации на хостинге мы заходим в контроль-панель. Мы должны увидеть наши ресурсы, в частности, облако:

А справа от него будет идентификатор.

3. Идентификатор каталога. На той же странице контроль панели, ниже облака мы увидим каталог:

Также, справа мы можем скопировать его идентификатор.

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

Установка Terraform

Terraform является клиентом и необходимо выполнить установку на компьютер, с которого планируется управление инфраструктурой. Актуальная инструкция по развертыванию представлена на официальном сайте. На текущий момент клиент может быть установлен из репозитория, с использованием бинарника, собран из исходников, а также с помощью choco на Windows или brew на Mac OS. В нашем примере будут рассмотрены установка на Ubuntu и Rocky Linux из репозитория, а также загрузка бинарника.

Ubuntu (Debian)

Обновляем список пакетов:

apt update

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

apt install gnupg software-properties-common curl

* где:

• gnupg — программа для шифровки и дешифровки цифровых подписей. Нужна для работы с репозиториями.
• software-properties-common — утилита для работы с репозиториями.
• curl — отправка GET, POST и других запросов.

Установим в систему ключ для репозитория:

curl -fsSL https://apt.releases.hashicorp.com/gpg | apt-key add -

Добавляем репозиторий:

apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"

Обновляем список пакетов, чтобы загрузить списки с нового репозитория:

apt update

Можно устанавливать terraform:

apt install terraform

Rocky Linux

Устанавливаем утилиту для работы с репозиториями:

yum install yum-utils

Добавляем репозиторий:

yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

Устанавливаем terraform:

yum install terraform

Скачиваем бинарник

Суть данного метода — скачать бинарный файл и перенести его в каталог /usr/local/bin.

Таким же образом устанавливаем terraform на Windows.

Для начала нам понадобятся утилиты unzip и wget. Устанавливаются они по-разному, в зависимости от дистрибутива Linux.

а) Ubuntu / Debian:

apt install unzip wget

б) Rocky Linux:

yum install unzip wget

Переходим к загрузке бинарного файла. Посмотреть ссылку на него можно на странице официального сайта:

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

wget https://releases.hashicorp.com/terraform/1.1.7/terraform_1.1.7_linux_amd64.zip

* в нашем примере будет загружена версия 1.1.7.

Распакуем архив командой:

unzip terraform_*_linux_amd64.zip

Перенесем распакованный бинарник в каталог:

mv terraform /usr/local/bin/

После установки

Убедимся, что terraform работает. Для этого вводим команду:

terraform -version

Мы должны получить что-то на подобие:

Terraform v1.1.7
on linux_amd64

Также рекомендуется установить автоподстановки:

terraform -install-autocomplete

Это позволит нам завершать команды terraform с помощью клавиши Tab.

Теперь создадим каталог, в котором будем работать со сценариями для тераформа:

mkdir -p /opt/terraform/yandex

* в моем примере я решил работать в каталоге /opt/terraform/yandex.

Перейдем в созданный каталог:

cd /opt/terraform/yandex

Мы готовы приступить непосредственно к работе с terraform.

Установка провайдера

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

На сайте Hashicorp можно найти все поддерживаемые провайдеры. Как говорилось выше, мы будем работать с Yandex.Cloud. Рассмотрим подробнее установку провайдера для работы с ним.

В нашем рабочем каталоге создаем первый файл:

vi main.tf

terraform {
  required_version = "= 1.1.7"

  required_providers {
    yandex = {
      source  = "yandex-cloud/yandex"
      version = "= 0.73"
    }
  }
}

provider "yandex" {
  token     = "<OAuth>"
  cloud_id  = "<идентификатор облака>"
  folder_id = "<идентификатор каталога>"
  zone      = "<зона доступности по умолчанию>"
}

* где:

• terraform required_version — версия клиента terraform, для которого должен запускаться сценарий. Параметр не обязательный, но является правилом хорошего тона и может помочь избежать некоторых ошибок, которые возникнут из-за несовместимости при работе в команде.
• required_providers version — версия провайдера. Мы можем указать, как в данном примере, необходимость использовать конкретную версию, а можно с помощью знака >= или <= указать не выше или не ниже определенной.
• token — OAuth-токен для прохождения авторизации. Был нами получен после регистрации на хостинге (описание выше).
• cloud_id — идентификатор для облака, в котором будут создаваться ресурсы. Также получен был нами заранее.
• folder_id — идентификатор каталога, который также был получен в начале инструкции.
• zone — ресурсы, которые хранятся на мощностях Яндекс разделены по зонам. Каждая зона — это определенная географическая локация центра обработки данных. Список доступных зон можно посмотреть на странице Зоны доступности.

Теперь выполним команду:

terraform init

Система загрузит нужные файлы и установит провайдер:

Initializing the backend...

Initializing provider plugins...
- Finding latest version of yandex-cloud/yandex...
- Installing yandex-cloud/yandex v0.73.0...
- Installed yandex-cloud/yandex v0.73.0 (self-signed, key ID E40F590B50BB8E40)
...
Terraform has been successfully initialized!
...

Мы готовы двигаться дальше.

Работа с ресурсами

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

Создание ресурсов

В нашем рабочем каталоге создадим новый файл:

vi infrastructure1.tf

Напишем минимально необходимый сценарий для создания виртуальной машины: 

data "yandex_compute_image" "ubuntu_image" {
  family = "ubuntu-2004-lts"
}

resource "yandex_compute_instance" "vm-test1" {
  name = "test1"

  resources {
    cores  = 2
    memory = 2
  }

  boot_disk {
    initialize_params {
      image_id = data.yandex_compute_image.ubuntu_image.id
    }
  }

  network_interface {
    subnet_id = yandex_vpc_subnet.subnet_terraform.id
    nat       = true
  }

  metadata = {
    user-data = "${file("./meta.yml")}"
  }

}

resource "yandex_vpc_network" "network_terraform" {
  name = "net_terraform"
}

resource "yandex_vpc_subnet" "subnet_terraform" {
  name           = "sub_terraform"
  zone           = "ru-central1-a"
  network_id     = yandex_vpc_network.network_terraform.id
  v4_cidr_blocks = ["192.168.15.0/24"]
}

* где:

• data — позволяет запрашивать данные. В данном примере мы обращаемся к ресурсу yandex_compute_image с целью поиска идентификатора образа, с которого должна загрузиться наша машина.
  • yandex_compute_image — ресурс образа. Его название определено провайдером.
  • ubuntu_image — произвольное название ресурса. Его мы определили сами и будем использовать в нашем сценарии.
  • ubuntu-2004-lts — в нашем примере мы запрашиваем данные ресурса, который ищем по family с названием ubuntu-2004-lts. Данное название можно посмотреть в контроль панели хостинга — нужно выбрать образ и кликнуть по нему. Откроется страница с дополнительной информацией. В данном случае ubuntu-2004-lts соответствуем Ubuntu 20.04 LTS.
• resource — позволяет создавать различные ресурсы.
  • yandex_compute_instance — ресурс виртуальной машины. Его название определено провайдером.
  • vm-test1 — наше название ресурса для виртуальной машины.
  • yandex_vpc_network — ресурс сети, определенный провайдером.
  • network_terraform — наше название для ресурса сети.
  • yandex_vpc_subnet — ресурс подсети, определенный провайдером.
  • subnet_terraform — наше название для ресурса подсети.
  • metadata — обратите особое внимание на передачу метеданных. В данном примере мы передаем содержимое файла, а сам файл рассмотрим ниже.

** в нашем примере будет создана виртуальная машина с названием test1, 2 CPU, 2 Gb RAM в сети 192.168.15.0/24 на базе Ubuntu 20.04 LTS.
*** обратите внимание, что мы указали идентификатор той подсети для виртуальной машины, которую создали также с помощью нашего сценария terraform.

Создаем файл с метеданными:

meta.yml

#cloud-config
users:
  - name: dmosk
    groups: sudo
    shell: /bin/bash
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    ssh-authorized-keys:
      - ssh-rsa AAAAB3Nza..................UXFDCb/ujrK4KbpCyvk=

* в данном файле мы опишем пользователя, под которым мы сможем подключиться к нашему серверу по SSH:

• #cloud-config — как выяснилось, этот комментарий обязательный.
• name — имя пользователя, который будет создан на виртуальной машине.
• groups — в какую группу добавить пользователя.
• shell — оболочка shell по умолчанию.
• sudo — правило повышения привилений.
• ssh-authorized-keys — список ключей, которые будут добавлены в authorized_keys.

Попробуем испытать наш сценарий. Сначала вводим:

terraform plan

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

После того, как мы убедимся в корректности действий, применяем настройку:

terraform apply

Мы еще раз увидим, что будет выполнено, а также получим запрос на подтверждение действий — вводим yes:

Enter a value: yes

Terraform выполнит необходимые действия. Мы можем перейти в контроль-панель хостинга и убедиться, что наша виртуальная машина создалась.

Редактирование данных

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

vi infrastructure1.tf

Внести нужные изменения, например:

  ...
  resources {
    cores  = 4
    memory = 4
  }
  ...

* в нашем конкретном случае, мы увеличили количество процессоров и объем памяти для созданной виртуальной машины.

Однако, некоторые изменения требуют остановки виртуальной машины. В этом случае мы получим ошибку при попытке применить новые настройки с текстом:

Error: Changing the `secondary_disk`, `resources`, `platform_id`, `network_acceleration_type` or `network_interfaces` on an instance requires stopping it. To acknowledge this action, please set allow_stopping_for_update = true in your config file.

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

...
resource "yandex_compute_instance" "vm-test1" {
  name = "test1"
  allow_stopping_for_update = true

...

* для нашей машины test1 мы указали опцию allow_stopping_for_update, которая говорит о том, что работу ресурса можно останавливать для внесения изменений.

Строим план:

terraform plan

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

      ~ resources {
          ~ cores         = 2 -> 4
          ~ memory        = 2 -> 4
            # (2 unchanged attributes hidden)
        }

Применяем настройки:

terraform apply

Проверяем через контроль-панель, что изменения вступили в силу.

Удаление ресурсов

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

1. Например, можно указать count = 0:

resource "yandex_compute_instance" "vm-test1" {
  count = 0
  ...

2. Можно закомментировать или удалить строки ресурса из файла tf.

3. Если мы хотим оставить содержимое файлов нетронутым, но при этом удалить все ресурсы, вводим:

terraform destroy

Утилита пройдет по всем файлам tf в директории, найдет ресурсы и выполнит их удаление.

Файл state

Очень важно уметь работать с файлом состояния terraform, а также понять, что это. Данный файл появляется после первого применения сценария в том же рабочем каталоге:

ls

terraform.tfstate

В нем содержатся все изменения, которые происходили с применением terraform. Без него последний не будет знать, что уже было сделано — на практике это приведет к дублированию инфраструктуры, то есть, если мы создали сервер, потеряли файл состояния и снова запустили terraform, он создаст еще один сервер. Для больших инфраструктур с большой историей все намного критичнее.

И так, файл состояния важен с точки зрения понимания инфраструктуры самим terraform. Также у него есть еще одна функция — блокировка параллельных выполнений. Это важно для работы в командах, где одновременные действия могут привести к неожиданным последствиям. Чтобы этого не произошло, terraform создает блокировку, которая запрещает выполнения, если уже идет процесс применения плана.

Из вышесказанного делаем выводы:

• Файлы состояния нужно бэкапить.
• Они должны находиться в надежном месте.
• У всех инженеров, которые работают с инфраструктурой должен быть доступ к файлу состояния. Они не должны его копировать на свои компьютеры и использовать индивидуально.

Рассмотрим возможность хранения данного файла состояния на облачном хранилище Яндекс.

Сначала мы должны создать хранилище. Это можно сделать через веб-интерфейс, но мы это сделаем в terraform.

Но сначала мы сделаем файл:

vi variables.tf

variable "yandex_folder_id" {
  type        = string
  default     = "<идентификатор каталога>"
}

* где yandex_folder_id — название для нашей переменной; <идентификатор каталога> — тот идентификатор, который мы указали в файле main под аргументом folder_id.

Теперь откроем файл main:

vi main.tf

И отредактируем значение folder_id на:

  ...
  folder_id = var.yandex_folder_id
  ...

* в данном примере мы теперь задаем folder_id не явно, а через созданную переменную.

Теперь создадим файл:

vi yandex_storage_bucket.tf

resource "yandex_iam_service_account" "sa" {
  folder_id = var.yandex_folder_id
  name      = "sa-dmosk"
}

resource "yandex_resourcemanager_folder_iam_member" "sa-editor" {
  folder_id = var.yandex_folder_id
  role      = "storage.editor"
  member    = "serviceAccount:${yandex_iam_service_account.sa.id}"
}

resource "yandex_iam_service_account_static_access_key" "sa-static-key" {
  service_account_id = yandex_iam_service_account.sa.id
  description        = "Static access key for object storage"
}

resource "yandex_storage_bucket" "state" {
  bucket     = "tf-state-bucket-dmosk"
  access_key = yandex_iam_service_account_static_access_key.sa-static-key.access_key
  secret_key = yandex_iam_service_account_static_access_key.sa-static-key.secret_key
}

* рассмотрим файл немного подробнее:

• yandex_iam_service_account — создание ресурса для учетной записи. В нашем примере она будет иметь название sa-dmosk и входить в системный каталог yandex_folder_id (переменная, которую мы создали ранее).
• yandex_resourcemanager_folder_iam_member — создание роли. Она будет иметь доступ для редактирования хранилищ. В состав роли войдет созданная запись sa (с именем sa-dmosk).
• yandex_iam_service_account_static_access_key — создаем ключ доступа для нашей сервисной учетной записи.
• yandex_storage_bucket — создаем хранилище с названием tf-state-bucket-dmosk.

Создаем еще один файл:

vi outputs.tf

output "access_key" {
  value = yandex_iam_service_account_static_access_key.sa-static-key.access_key
  sensitive = true
}
output "secret_key" {
  value = yandex_iam_service_account_static_access_key.sa-static-key.secret_key
  sensitive = true
}

* это делается для получения значений аргументов access_key и secret_key и сохранения данных значений в файле состояния. Если access_key можно посмотреть в панели Яндекса, то secret_key мы увидеть не можем.

Строим план и применяем настройки:

terraform plan

terraform apply

Заходим в контроль-панель Яндекса и видим, что у нас создалось хранилище. Его мы будем использовать для хранения файлов состояний terraform.

Открываем наш файл main:

vi main.tf

Добавляем:

terraform {
  ...

  backend "s3" {
    endpoint   = "storage.yandexcloud.net"
    bucket     = "tf-state-bucket-dmosk"
    region     = "ru-central1-a"
    key        = "terraform/infrastructure1/terraform.tfstate"
    access_key = "<access_key>"
    secret_key = "<secret_key >"

    skip_region_validation      = true
    skip_credentials_validation = true
  }
}

* в раздел terraform мы добавили инструкцию для хранения файла state. В нашем примере он будет размещен на бакете tf-state-bucket-dmosk по пути terraform/infrastructure1/terraform.tfstate.
** особое внимание обратите на access_key и secret_key. В разделе terraform мы не можем указать переменные, как это делали при создании хранилища. Сами значения можно найти в нашем локальном файле state.

Используем команду:

terraform init

Система снова инициализирует состояние текущего каталога и создаст файл state на удаленном хранилище. Чтобы убедиться, можно зайти в контроль панель, найти наше хранилище, а в нем — файл terraform/infrastructure1/terraform.tfstate.

Реальный пример

Мы развернем 2 веб-сервера и поместим их за Network load balancer.

Для этого мы создадим новый рабочий каталог:

mkdir -p /opt/terraform/yandex-network-load balancer

И перейдем в него:

cd /opt/terraform/yandex-network-load balancer

Подразумевается, что все инфраструктура создается с нуля, поэтому нужно либо удалить предыдущие наработки, либо создать новый сервисный аккаунт для storage.

Мы создадим 5 файлов:

1. main.tf — в нем мы опишем инструкции для init, а именно требования к версии клиента terraform, провайдера.
2. web-servers.tf — сценарий для создания 2-х веб-серверов.
3. network-load-balancer.tf — создание Network Load Balancer.
4. variables.tf — описание переменных.
5. outputs.tf — вывод значений после отработки terraform на экран и в файл состояния.

1. Создаем файл main.tf:

vi main.tf

terraform {
  required_version = "= 1.1.7"

  required_providers {
    yandex = {
      source  = "yandex-cloud/yandex"
      version = "= 0.73"
    }
  }
}
provider "yandex" {
  token     = "<OAuth>"
  cloud_id  = "<идентификатор облака>"
  folder_id = "<идентификатор каталога>"
  zone      = "<зона доступности по умолчанию>"
}

* это стандартный вариант файла main.tf, который мы разбирали в начале.

2. web-servers.tf:

vi web-servers.tf

data "yandex_compute_image" "lamp" {
  family = "lamp"
}

data "yandex_compute_image" "lemp" {
  family = "lemp"
}

resource "yandex_compute_instance" "vm-test1" {
  name                      = "vm-test1"
  allow_stopping_for_update = true

  resources {
    cores  = 2
    memory = 2
  }

  boot_disk {
    initialize_params {
      image_id = data.yandex_compute_image.lamp.id
    }
  }

  network_interface {
    subnet_id = yandex_vpc_subnet.subnet_terraform.id
    nat       = true
  }

}

resource "yandex_compute_instance" "vm-test2" {
  name                      = "vm-test2"
  allow_stopping_for_update = true

  resources {
    cores  = 2
    memory = 2
  }

  boot_disk {
    initialize_params {
      image_id = data.yandex_compute_image.lemp.id
    }
  }

  network_interface {
    subnet_id = yandex_vpc_subnet.subnet_terraform.id
    nat       = true
  }

}

resource "yandex_vpc_network" "network_terraform" {
  name = "network_terraform"
}

resource "yandex_vpc_subnet" "subnet_terraform" {
  name           = "subnet_terraform"
  zone           = "ru-central1-a"
  network_id     = yandex_vpc_network.network_terraform.id
  v4_cidr_blocks = ["192.168.15.0/24"]
}

* в данном примере мы создадим 2 виртуальные машины — одну с образом lamp (Apache), вторую на lemp (NGINX).

3. network-load-balancer.tf:

vi network-load-balancer.tf

resource "yandex_lb_network_load_balancer" "lb-dmosk" {
  name = "lb-dmosk"

  listener {
    name = "listener-web-servers"
    port = 80
    external_address_spec {
      ip_version = "ipv4"
    }
  }

  attached_target_group {
    target_group_id = yandex_lb_target_group.web-servers.id

    healthcheck {
      name = "http"
      http_options {
        port = 80
        path = "/"
      }
    }
  }
}

resource "yandex_lb_target_group" "web-servers" {
  name = "web-servers-target-group"

  target {
    subnet_id = yandex_vpc_subnet.subnet_terraform.id
    address   = yandex_compute_instance.vm-test1.network_interface.0.ip_address
  }

  target {
    subnet_id = yandex_vpc_subnet.subnet_terraform.id
    address   = yandex_compute_instance.vm-test2.network_interface.0.ip_address
  }
}

* в данном сценарии мы:

• создаем target_group из 2-х наших веб-серверов.
• создаем балансировщик lb-dmosk.
• привязываем к балансировщику target_group.

4. variables.tf:

vi variables.tf

variable "yandex_folder_id" {
  type        = string
  default     = "<folder_id>"
}

* создадим переменную с folder_id, в котором мы должны работать. Выше мы уже делали такую переменную.

5. outputs.tf:

vi outputs.tf

output "lb_ip_address" {
  value = yandex_lb_network_load_balancer.lb-dmosk.*
}

* на самом деле, это не обязательно — информацию о созданном балансировщике можно посмотреть в контроль панели, но для примера мы решили это рассмотреть.

Готово. После применения данного сценария мы получим то, что хотели — две виртуальные машины + балансировщик сети, который будет распределять запросы между данными серверами.

Источник: https://www.dmosk.ru/instruktions.php?object=terraform

В данной инструкции будут рассмотрены небольшие сценарии работы с Gitlab Pipelines. Мы приведем примеры использования наиболее востребованных опций при работе с CI/CD. По мере необходимости, база шаблонов будет пополняться.

Шаблоны

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

1. Минимальный сценарий. Для небольших заданий, состоящих из пары заданий:

stages:
  - build

TASK_NAME:
  stage: build
  script:
    - ./build_script.sh

* где:

• stages — описание стадий нашего пайплайна. В данном примере, всего одна.
• TASK_NAME — имя нашей задачи.
  • stage — стадия, к которой относится наше задание.
  • script — набор скриптов для выполнения.

2. Стандартный цикл при сборке. Обычно, процесс CI/CD включает следующие шаги:

• Сборка пакета.
• Тестирование.
• Доставка.
• Развертывание.

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

stages:
  - build
  - test
  - delivery
  - deploy

build-job:
  stage: build
  script:
    - echo "Start build job"
    - build-script.sh

test-job:
  stage: test
  script:
    - echo "Start test job"
    - test-script.sh

delivery-job:
  stage: delivery
  script:
    - echo "Start delivery job"
    - delivery-script.sh

deploy-job:
  stage: deploy
  script:
    - echo "Start deploy job"
    - deploy-script.sh

Задания

В данном разделе мы рассмотрим опции, которые могут применяться при описании задания. Общий синтаксис:

<TASK_NAME>:
  <OPTION1>: ...
  <OPTION2>: ...

Мы перечислим лишь часто встречаемые опции. Полный список можно найти в официальной документации.

Stage

Опция указывает, к какой стадии относится задание. Например:

stages:
  - build
  - test

TASK_NAME:
  ...
  stage: build

TASK_NAME:
  ...
  stage: test

Сами же стадии описываются в общей директиве stages.

Также есть две стадии, которые не требуют предварительного определения в stages:

• .pre — запускает до выполнения основных заданий конвейера.
• .post — выполняется в конце, после выполнения основных заданий нашего пайплайна.

Например:

stages:
  - build
  - test

getVersion:
  stage: .pre
  script:
    - VERSION=$(cat VERSION_FILE")
    - echo "VERSION=${VERSION}" > variables.env
  artifacts:
    reports:
      dotenv: variables.env

* в данном примере мы до того, как начнем проходить по всем заданиям сборки, определим переменную с версией, прочивав ее из файла, и передадим артефактом в качестве системной переменной VERSION.

Image

Задаем имя образа, если наше задание выполняется в контейнере docker:

TASK_NAME:
  ...
  image: debian:11

Before_script

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

TASK_NAME:
  ...
  before_script:
    - echo "Run before_script"

Script

Основная часть, где выполняются задания сценария, описана в опции script. Рассмотрим ее подробнее.

1. Описание массива команд. Мы просто перечисляем списком те команды, которые необходимо последовательно выполнить нашему сценарию в конкретной задаче:

TASK_NAME:
  ...
  script:
    - command1
    - command2

2. Длинные команды, разбитые на несколько строк. Нам может потребоваться выполнить команды в виде скрипта (с операторами сравнения, например). В этом случае будет удобна многострочная запись. Ее можно указать разными способами.

Индикатор | :

TASK_NAME:
  ...
  script:
    - |
      command_line1
      command_line2

* для него каждая новая строка является переходом к новой команде или части оператора. По сути, это близко к логике скрипта shell.

Индикатор > :

TASK_NAME:
  ...
  script:
    - >
      command_line1
      command_line1_continue

      command_line2
      command_line2_continue

* данный индикатор интерпретирует новую команду после пустой строки.

After_script

Набор команд, которые запускаются после scripts, даже, при неудачном завершении последнего.

TASK_NAME:
  ...
  script:
    ...
  after_script:
    - command1
    - command2

Artifacts

Артефакты представляют из себя промежуточные сборки или файлы, которые могут передаваться от одного этапа — другому.

1. Например, так можно указать, какие файлы или каталоги будут артефактами:

TASK_NAME:
  ...
  artifacts:
    paths:
      - ${PKG_NAME}.deb
      - ${PKG_NAME}.rpm
      - *.txt
      - configs/

* в моем примере, в артефакты попадут все файлы, название которых заканчивается на txt, файлы ${PKG_NAME}.deb и ${PKG_NAME}.rpm, а также каталог configs. Где ${PKG_NAME} — переменная (подробнее о переменных ниже).

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

TASK_NAME_2:
  ...
  script:
    - cat *.txt
    - yum -y localinstall ${PKG_NAME}.rpm
    - apt -y install ./${PKG_NAME}.deb

2. Также мы можем передать системные переменные, которые были нами переданы в файл:

TASK_NAME:
  ...
  script:
    - echo -e "VERSION=1.1.1" > variables.env
  ...
  artifacts:
    reports:
      dotenv: variables.env

* в данном примере мы передадим системную переменную VERSION со значением 1.1.1 через файл variables.env.

3. При необходимости, мы можем исключить из списка определенные файлы по названию или маске:

TASK_NAME:
  ...
  artifacts:
    paths:
      ...
    exclude:
      - ./.git/**/*

* в данном примере мы исключаем каталог .git, в котором, как правило, хранятся метаданные репозитория.
** обратите внимание, что в отличие от paths, exclude не берет файлы и каталоги рекурсивно и нужно явно указывать объекты.

Extends

Позволяет вынести часть сценария в отдельный блок и объединить его с заданием. Чтобы это лучше понять, рассмотрим конкретный пример:

.my_extend:
  stage: build
  variables:
    USERNAME: my_user
  script:
    - extend script

TASK_NAME:
  extends: .my_extend
  variables:
    VERSION: 123
    PASSWORD: my_pwd
  script:
    - task script

И так, в нашем задании TASK_NAME мы используем extends. В результате, задание примет такой вид:

TASK_NAME:
  stage: build
  variables:
    VERSION: 123
    PASSWORD: my_pwd
    USERNAME: my_user
  script:
    - task script

Что произошло:

• stage: build попало в задание из my_extend.
• произошло объединение variables, итого в задание попали VERSION, PASSWORD и USERNAME.
• script используется из задания (значения ключей не объединяются, приоритет за значением основного задания).

Environment

Позволяет указать системную переменную, которая будет создана для выполнения задания.

TASK_NAME:
  ...
  environment:
    RSYNC_PASSWORD: rpass
    EDITOR: vi

Release

Публикует релиз на портале Gitlab для нашего проекта.

TASK_NAME:
  ...
  release:
    name: 'Release $CI_COMMIT_TAG'
    tag_name: '$CI_COMMIT_TAG'
    description: 'Created using the release-cli'
    assets:
      links:
        - name: "myprogram-${VERSION}"
          url: "https://gitlab.com/master.dmosk/project/-/jobs/${CI_JOB_ID}/artifacts/raw/myprogram-${VERSION}.tar.gz"
  rules:
    - if: $CI_COMMIT_TAG

* обратите внимание, что мы применяем правило if (о нем ниже).

Директивы правил и ограничений

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

Rules

Правила, при соблюдении которых наше задание может быть запущено. Примеры работы с директивой rules приведены ниже.

When

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

Needs

Тоже набор правил, требующий определенных условий для запуска задачи. Все директивы условий и правил описаны ниже.

Правила и условия

Мы можем выполнять или пропускать задания, в зависимости от выполнения определенных условий. Для этого существует несколько полезных директив, которые мы рассмотрим в данном разделе.

Rules

Регламентирует различные правила, определенные с помощью:

• if.
• changes.
• exists.
• allow_failure.
• variables.

1. Оператор if. Позволяем проверить условие, например, если переменная равна определенному значению:

TASK_NAME:
  ...
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

* в данном примере коммит должен быть выполнен в бранче по умолчанию.

2. Изменения затронули определенные файлы. Проверка выполняется с помощью опции changes.

В данном примере, файл script.sql:

TASK_NAME:
  ...
  rules:
    - changes:
        - script.sql

3. Несколько условий. Условий для начала выполнения задания может быть несколько. Рассмотрим несколько примеров.

а) При условии, что коммит выполнен в бранче по умолчанию И изменения затронули файл script.sql:

TASK_NAME:
  ...
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      changes:
        - script.sql

б) При условии, что коммит выполнен в бранче по умолчанию ИЛИ изменения затронули файл script.sql

TASK_NAME:
  ...
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
    - changes:
        - script.sql

4. Проверка на существование файла. Определяется с помощью exists:

TASK_NAME:
  ...
  rules:
    - exists:
        - script.sql

* задание будет выполняться только в случае присутствия файла script.sql.

5. Разрешить сбой задания. Задается с помощью allow_failure:

TASK_NAME:
  ...
  rules:
    - allow_failure: true

* в данном примере наш конвейер продолжит работу, если задание TASK_NAME будет выполнено с ошибкой.

6. Определение переменной в зависимости от условия. Для этого используются вместе if и variables:

TASK_NAME:
  ...
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      variables:
        DEPLOY_VARIABLE: "production"
    - if: '$CI_COMMIT_BRANCH =~ demo'
      variables:
        DEPLOY_VARIABLE: "demo"

When

Определяет условия запуска задания. Возможные значения:

• on_success (по умолчанию) — если все задания на более ранних этапах завершились успешно или имеют allow_failure: true.
• manual — запуск вручную (в панели pipeline появится кнопка запуска).
• always — запускать всегда, независимо от предыдущих результатов.
• on_failure — только в случае сбоя, хотя бы, одного задания на более раннем этапе.
• delayed — отложить запуск задания. Контролировать срок можно с помощью директивы start_in.
• never — никогда не запускать задание.

Разберем примеры.

1. Manual:

TASK_NAME:
  ...
  when: manual

* задание не начнет выполняться, пока мы не нажмем кнопку запуска в GitLab CI/CD.

2. Always:

TASK_NAME:
  ...
  when: always

* задание будет выполняться всегда. Удобно, например, если нужно сформировать отчетный файл, независимо от результатов сборки.

3. On_failure:

TASK_NAME:
  ...
  on_failure: always

* задание будет выполняться при наличии ошибки на ранних этапах. Можно использовать для отправки уведомления.

4. Delayed:

TASK_NAME:
  ...
  when: delayed
  start_in: 30 minutes

* запуск задания будет отложен на 30 минут.

5. Never:

TASK_NAME:
  ...
  when: never

* задание не будет выполняться.

6. Использование вместе с if:

TASK_NAME:
  ...
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      when: manual

* в данном примере задание будет выполняться, если коммит прошел в основной ветке и если администратор подтвердил запуск.

Needs

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

Рассмотрим примеры.

1. Artifacts. Принимает значение true (по умолчанию) и false. Для запуска задания нужно, чтобы на предыдущих этапах были загружены артефакты. Запись:

TASK_NAME:
  ...
  needs:
    - artifacts: false

… позволяет начать выполнение задания без этого.

2. Job. Позволяет начать выполнение задачи только после завершения другого задания:

TASK_NAME:
  ...
  needs:
    - job: createBuild

* в нашем примере задача начнет выполняться не раньше завершения задачи с названием createBuild.

Переменные

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

Пользовательские переменные

Задаются с помощью директивы variables.

Можно определить глобально для всех заданий:

variables:
  PKG_VER: "1.1.1"

Или для конкретного задания:

TASK_NAME:
  ...
  variables:
    PKG_VER: "1.1.1"

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

  script:
    - echo ${PKG_VER}

Переменные Gitlab

Данный тип переменных поможет нам управлять процессом сборки. Перечислим данные переменные с описанием их свойств:

Дополнительные параметры

В данном разделе мы рассмотрим различные опции, которые не вошли в другие разделы.

1. Workflow. Позволяем задать общие правила запуска для всего конвейера. Рассмотрим пример с официального сайта:

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /-draft$/
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

В данном примере конвейер:

• Не будет запущен, если название коммита содержит текст draft.
• Будет запущен, если пайплайн сработал после merge request.
• Будет запущен, если изменения внесены в основную ветку репозитория.

2. Значения по умолчанию. Задаются в директиве default. Опции с данными значениями будут использоваться во всех заданиях или могут быть переопределены на уровне конкретного задания.

Пример:

default:
  image: centos:7
  tags:
    - ci-test

* мы определили опцию с именем образа (например, образа docker) и тег (теги могут быть необходимы для запуска некоторых runner).

3. Импорт конфигурации из другого файла yml. Может быть полезным, например, для написания общей части сценария, которую мы захотим применять ко всем pipeline или для разделения громоздкого сценария на составные части. Выполняется с помощью опции include. Имеет различные варианты подгрузки файлов. Рассмотрим их подробнее.

а) подключение локального файла (local):

include:
  - local: .gitlab/ci/build.yml

б) коллекции шаблонов (template):

include:
  - template: Custom/.gitlab-ci.yml

* в данном примере мы подключим к нашему сценарию содержимое файла Custom/.gitlab-ci.yml.

в) внешний файл доступный по HTTP (remote):

include:
  - remote: 'https://gitlab.dmosk.ru/main/build.yml'

г) другой проект:

include:
  - project: 'public-project'
    ref: main
    file: 'build.yml'

4. !reference tags. Позволяет описать сценарий и повторно его использовать для разных стадий и задач нашего CI/CD.

Например:

.apt-cache:
  script:
    - apt update
  after_script:
    - apt clean all

install:
  stage: install
  script:
    - !reference [.apt-cache, script]
    - apt install nginx

update:
  stage: update
  script:
    - !reference [.apt-cache, script]
    - apt upgrade
    - !reference [.apt-cache, after_script]

* давайте разберемся, что происходит в нашем примере.

• Мы создали задачу apt-cache. Точка в начале названия говорит системе, что данную задачу не нужно стартовать автоматически при запуске pipeline. Созданная задача состоит из двух секций script и after_script. Секций может быть больше.
• Мы выполняем стадию install. В одной из строк выполнения мы вызываем apt-cache (только команды из раздела script).
• При выполнении стадии update мы вызываем apt-cache два раза — первый выполняет команды раздела script, второй — after_script.

Источник: https://www.dmosk.ru/miniinstruktions.php?mini=gitlab-pipeline

В данной инструкции мы рассмотрим пример docker-compose файла для организации системы мониторинга на базе Prometheus. Мы получим:

• Базу данных Prometheus и интерфейс для выполнения PromQL.
• Визуализацию с помощью Grafana.
• Сбор метрик через Node Exporter.
• Мониторинг HTTP с использованием Blackbox.
• Отправку уведомлений в Telegram с помощью Alertmanager.

Мы будем работать в среде Linux, хотя полученный файл docker-compose можно применять где угодно. Останавливаться подробно на описании docker-compose мы не будем.

Подготовка системы

Подразумевается, что у нас установлен Docker и docker-compose, в противном случае, можно воспользоваться инструкцией Установка Docker на Linux.

Создаем каталоги, где будем создавать наши файлы:

mkdir -p /opt/prometheus_stack/{prometheus,grafana,alertmanager,blackbox}

Создаем файл:

touch /opt/prometheus_stack/docker-compose.yml

Переходим в каталог prometheus_stack:

cd /opt/prometheus_stack

Дальше будем работать относительно него.

Prometheus + Node Exporter

Открываем файл:

vi docker-compose.yml

version: '3.9'

services:

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus:/etc/prometheus/
    container_name: prometheus
    hostname: prometheus
    command:
      - --config.file=/etc/prometheus/prometheus.yml
    ports:
      - 9090:9090
    restart: unless-stopped
    environment:
      TZ: "Europe/Moscow"
    networks:
      - default

  node-exporter:
    image: prom/node-exporter
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
    container_name: exporter
    hostname: exporter
    command:
      - --path.procfs=/host/proc
      - --path.sysfs=/host/sys
      - --collector.filesystem.ignored-mount-points
      - ^/(sys|proc|dev|host|etc|rootfs/var/lib/docker/containers|rootfs/var/lib/docker/overlay2|rootfs/run/docker/netns|rootfs/var/lib/docker/aufs)($$|/)
    ports:
      - 9100:9100
    restart: unless-stopped
    environment:
      TZ: "Europe/Moscow"
    networks:
      - default

networks:
  default:
    ipam:
      driver: default
      config:
        - subnet: 172.28.0.0/16

* в данном примере мы создаем 2 сервиса — prometheus и node-exporter. Также мы отдельно определили подсеть 172.28.0.0/16, в которой будут находиться наши контейнеры docker.

Создаем конфигурационный файл для prometheus:

vi prometheus/prometheus.yml

scrape_configs:
  - job_name: node
    scrape_interval: 5s
    static_configs:
    - targets: ['node-exporter:9100']

* в данном примере мы прописываем наш node-exporter в качестве таргета.

Запускаем контейнеры:

docker-compose up -d

Ждем несколько секунд и можно пробовать подключиться. Открываем браузер и переходим по адресу http://<IP-адрес сервера>:9090 — мы должны увидеть страницу Prometheus:

Переходим по адресу http://<IP-адрес сервера>:9100 — мы должны увидеть страницу Node Exporter:

Мы движемся в правильном направлении. Идем дальше.

Grafana

Добавим к нашему стеку графану.

Открываем файл:

vi docker-compose.yml

Добавляем:

version: '3.9'

services:
  ...
  grafana:
    image: grafana/grafana
    user: root
    depends_on:
      - prometheus
    ports:
      - 3000:3000
    volumes:
      - ./grafana:/var/lib/grafana
      - ./grafana/provisioning/:/etc/grafana/provisioning/
    container_name: grafana
    hostname: grafana
    restart: unless-stopped
    environment:
      TZ: "Europe/Moscow"
    networks:
      - default

...

* по аналогии с другими сервисами, мы добавили сервис для графаны.

Перезапустим контейнеры:

docker-compose up -d

Открываем браузер и переходим по адресу http://<IP-адрес сервера>:3000 — мы должны увидеть стартовую страницу Grafana.

Для авторизации вводим admin / admin. После система потребует ввести новый пароль.

Настроим связку с Prometheus. Кликаем по иконке Configuration — Data Sources:

Переходим к добавлению источника, нажав по Add data source:

Среди списка источников данных находим и выбираем Prometheus, кликнув по Select:

Задаем параметры для подключения к Prometheus:

Сохраняем настройки, кликнув по Save & Test:

Добавим дашборд для мониторинга с node exporter. Для этого уже есть готовый вариант.

Кликаем по изображению плюса и выбираем Import:

Вводим идентификатор дашборда. Для Node Exporter это 1860:

Кликаем Load — Grafana подгрузит дашборд из своего репозитория — выбираем в разделе Prometheus наш источник данных и кликаем по Import:

Мы увидим страницу с настроенными показателями метрик. Можно пользоваться.

Настройка оповещений с AlertManager

В нашем примере мы настроим отправку уведомлений на телеграм бот. Само оповещение будет выполнять AlertManager, который интегрируется с Prometheus.

Для начала подготовим наш бот телеграм. Создадим нового — для этого открываем телеграм и ищем @my_id_bot:

Приложение покажет наш идентификатор. Записываем — он нам потребуется позже.

Теперь создаем бота. Ищем @BotFather:

Переходим в чат с найденным BotFather и запускаем бота:

Создаем бота, последовательно введя команду /newbot и отвечая на запросы мастера:

* в нашем примере мы создаем бота prometheus_alert с именем учетной записи DmoskPrometheusBot.

Переходим в чат с созданным ботом, кликнув по его названию:

Запускаем бота:

С ботом мы закончили. Переходим к docker.

Открываем наш файл docker-compose:

vi docker-compose.yml

И добавляем:

version: '3.9'
  ...

  alertmanager-bot:
    command:
      - --alertmanager.url=http://alertmanager:9093
      - --log.level=info
      - --store=bolt
      - --bolt.path=/data/bot.db
      - --telegram.admin=573454381
      - --telegram.token=5472129845:AAFTQRdujqIHgWHbbVtfYWQQvzvIN98KBqg
    image: metalmatze/alertmanager-bot:0.4.3
    user: root
    ports:
      - 8080:8080
    container_name: alertmanager-bot
    hostname: alertmanager-bot
    environment:
      TZ: "Europe/Moscow"
    restart: unless-stopped
    volumes:
      - ./data:/data
    networks:
      - default

  alertmanager:
    image: prom/alertmanager:v0.21.0
    user: root
    ports:
      - 127.0.0.1:9093:9093
    volumes:
      - ./alertmanager/:/etc/alertmanager/
    container_name: alertmanager
    hostname: alertmanager
    environment:
      TZ: "Europe/Moscow"
    restart: unless-stopped
    command:
      - '--config.file=/etc/alertmanager/config.yml'
      - '--storage.path=/etc/alertmanager/data'
    networks:
      - default

...

* мы добавили два сервиса — alertmanager-bot (телеграм бот для prometheus alertmanager) и alertmanager (система оповещений в prometheus).

Теперь открываем конфигурационный файл для prometheus:

vi prometheus/prometheus.yml

И добавим строки:

...

rule_files:
  - 'alert.rules'

alerting:
  alertmanagers:
  - scheme: http
    static_configs:
    - targets:
      - "alertmanager:9093"

* в данном примере мы указали, что наш сервер мониторинга должен использовать в качестве системы оповещения alertmanager, который доступен по адресу alertmanager:9093. Также мы добавили файл alert.rules с описанием правил оповещения.

Создаем файл с правилами оповещения:

vi prometheus/alert.rules

groups: 
- name: test
  rules:
  - alert: PrometheusTargetMissing
    expr: up == 0
    for: 0m
    labels:
      severity: critical
    annotations:
      summary: "Prometheus target missing (instance {{ $labels.instance }})"
      description: "A Prometheus target has disappeared. An exporter might be crashed. VALUE = {{ $value }}  LABELS: {{ $labels }}"

* в данном примере мы добавили правило, которое будет срабатывать при недоступности узла (node-exporter).

Переходим к конфигурированию alertmanager:

vi alertmanager/config.yml

route:
    receiver: 'alertmanager-bot'

receivers:
- name: 'alertmanager-bot'
  webhook_configs:
  - send_resolved: true
    url: 'http://alertmanager-bot:8080'

* данная конфигурация позволяет отправлять оповещения с помощью webhook на сервис alertmanager-bot:8080 (наш телеграм бот для alertmanager).

Запускаем новые сервисы docker:

docker-compose up -d

Открываем браузер и переходим по адресу http://<IP-адрес сервера>:9090 — на вкладке Alerts мы должны увидеть нашу настройку:

Попробуем проверить работу оповещения. Отключаем наш node exporter:

docker stop exporter

На телеграм должно прийти оповещение:

Отправка уведомлений настроена.

Blackbox exporter

Переходим к настройке мониторинга http сервисов. В нашем примере мы будем проверять работу сайта dmosk.ru.

Открываем наш файл docker-compose:

vi docker-compose.yml

Добавим в него:

version: '3.9'

services:
  ...

  blackbox:
    image: prom/blackbox-exporter
    container_name: blackbox
    hostname: blackbox
    ports:
      - 9115:9115
    restart: unless-stopped
    command:
      - "--config.file=/etc/blackbox/blackbox.yml"
    volumes:
      - ./blackbox:/etc/blackbox
    environment:
      TZ: "Europe/Moscow"
    networks:
      - default

  ...

* сервис blackbox является компонентом Prometheus для мониторинга сетевых сервисов по различным протоколам.

Открываем конфигурационный файл prometheus:

vi prometheus/prometheus.yml

И дописываем:

scrape_configs:
  ...
  - job_name: 'blackbox'
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
        - https://www.dmosk.ru
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox:9115

...

* подобная конфигурация позволит создать дополнительное задание мониторинга сайта https://www.dmosk.ru.

Создаем конфигурационный файл blackbox:

vi blackbox/blackbox.yml

modules:
  http_2xx:
    prober: http
    timeout: 5s
    http:
      valid_http_versions: ["HTTP/1.1", "HTTP/2.0"]
      valid_status_codes: [200]
      method: GET
      no_follow_redirects: true
      fail_if_ssl: false
      fail_if_not_ssl: false
      fail_if_body_matches_regexp:
        - "Could not connect to database"
      fail_if_body_not_matches_regexp:
        - "Download the latest version here"
      fail_if_header_matches: # Verifies that no cookies are set
        - header: Set-Cookie
          allow_missing: true
          regexp: '.*'
      fail_if_header_not_matches:
        - header: Access-Control-Allow-Origin
          regexp: '(*|example.com)'
      tls_config:
        insecure_skip_verify: false
      preferred_ip_protocol: "ip4"
      ip_protocol_fallback: false

* во многом, данный пример взят с официальной страницы на Github.

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

vi prometheus/alert.rules

Добавим:

  ...

  - alert: BlackboxSlowProbe
    expr: avg_over_time(probe_duration_seconds[1m]) > 5
    for: 1m
    labels:
      severity: warning
    annotations:
      summary: Blackbox slow probe (instance {{ $labels.instance }})
      description: "Blackbox probe took more than 1s to completen  VALUE = {{ $value }}n  LABELS = {{ $labels }}"

  - alert: BlackboxProbeHttpFailure
    expr: probe_http_status_code <= 199 OR probe_http_status_code >= 400
    for: 0m
    labels:
      severity: critical
    annotations:
      summary: Blackbox probe HTTP failure (instance {{ $labels.instance }})
      description: "HTTP status code is not 200-399n  VALUE = {{ $value }}n  LABELS = {{ $labels }}"

* в данном примере мы создали два правила:

• BlackboxSlowProbe — предупреждать, если сайт открывается дольше 5 секунд.
• BlackboxProbeHttpFailure — реагировать, в случае получения кода ответа с ошибкой работы сайта (более 400).

Запускаем добавленный в докер сервис:

docker-compose up -d

Для визуализации мониторинга с помощью blackbox есть готовый дашборд в графане. Снова открываем страницу импорта:

Вводим идентификатор 7587 и выбираем источник (как делали при добавлении дашборда node exporter).

Источник https://www.dmosk.ru/miniinstruktions.php?mini=prometheus-stack-docker#prometheus

Сам Хельм в общих чертах рассмотрели в посте Helm: Kubernetes package manager — обзор, начало работы – теперь надо прикрутить его в Jenkins. И не просто прикрутить его вызов – а создать чарт, потому что сейчас приложение деплоится через “голые” манифест-файлы Kubernetes, в котором sed проставляет теги Докер-образа и значения переменных для загрузки на окружение через kubectl apply -f.

Данный пост очередной НЕ-HowTo, а пример знакомства с Helm: возьмём существующий проект, который уже деплоится в Kubernetes-кластер, обновим его манифесты, что бы использовать их с Helm, продумаем – как именно и куда будем деплоить, и создадим Jenkins-джобу.

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

В общем, ещё один пример того, как очередная задача из смутной идеи в голове превращается в рабочий сервис – длиннопост в вольном стиле, аналог AWS Elastic Kubernetes Service: автоматизация создания кластера, часть 1 — CloudFormation и AWS Elastic Kubernetes Service: — автоматизация создания кластера, часть 2 — Ansible, eksctl, где шаг за шагом реализуем свою задумку.

Планирование

Репозитории

Итак, у нас имеется некое веб-приложение, которое надо деплоить в Kubernetes.

Само приложение разбито на две части – фронтенд на React, хостится и деплоится в AWS S3, и бекенд – NodeJS, работает в Docker-контейнере.

Первый вопрос, который появляется в голове – монорепа, или нет?

Т.е. – где хранить код приложения, где – файлы чартов Helm-а, а где – jenkins-файлы?

Хотелось бы монорепу, и всё держать в одном репозитории, но у нас подобных проектов будет не один, и смысла под каждый писать отдельные дженкис-файлы нет. Тем более, что если (когда!) захочется что-то изменить в одном – то придётся делать это во всех по отдельности.

При этом и их файлы манифестов для Kubernetes будут практически одинаковы – и можно было бы заморочится вообще, и используя возможности шаблонизатора Go – использовать один общий чарт на всех.

Но так как их одинаковость пока под вопросом – запускаемые веб-проекты ещё только разрабатываются, да ещё и отдельными группами девелоперов – то чарты будем делать под каждый проект отдельно.

Значит, у нас будет:

• отдельный репозиторий с кодом проекта
  • там же в отдельной папке храним файлы чартов
• отдельный репозиторий с файлами для Jenkins-pipeline

Хочется прикрутить ещё и релизы, да ещё и связать их с Github Releases – но это, может быть, потом. В целом – реализуемо, и даже есть helm/chart-releaser.

Jenkins build steps

Дальше.

Билд Docker-образов – и билд/деплой самих чартов – делать одной джобой – или разными?

Сейчас у нас образы собираются в одной джобе, после чего пушатся в DockerHub, после чего девелопер должен сходить в джобу деплоймента, и при запуске в параметрах указать тег (номер билда) + дополнительные параметры:

Это, конечно, ни разу неудобно, поэтому переделаем.

Итак, будет один пайплайн, в котором нам надо:

1. чекаут кода проекта
2. линт чарта
3. сгенерить kubeconfig
4. helm install example-chart --dry-run --debug example-chart/
5. helm install example-chart example-chart/
6. тест деплоя – helm get manifest example-chart

Опционально – удалять с chart uninstall. Про удаление ресурсов вообще поговорим ниже.

Что ещё?

Namespaces

Ооо – нейспейсы жеж!

Что хочется:

• иметь возможность деплоить по одной кнопке в какой-то дефолтный namespace, имя которого зависит от проекта/приложения/чарта
• деплоить в кастомный namespace – по имени бранча репозитория, из которого запускался билд
• деплоить в вообще кастомный namespace – дать возможность указать его при старте джобы

А как их потом удалять?

Можно добавить вебхук из Гитхаба при delete-операциях, но во-первых часть проектов хостятся в Gitlab – хотя он тоже умеет в вебхуки. Но во-вторых – а все ли девелоперы всех команд будут удалять свои закрытые бранчи?

Т.е. тут проблема как раз из-за разных команд и разных проектов, а решение хочется иметь маскимально универсальное.

А удалять НС-ы надо – иначе будет пачка заброшенных ресурсов – подов, ингресов, волюмов, и т.д.

Что делать?…

Окей. А пусть будет какой-то дефолтный неймспейс. Например, чарт/приложение называются bttrm-apps – значит, для Dev-деплой джобы НС будем создавать bttrm-apps-dev-ns.

В джобе добавить параметр, в нём сделать возможность выбора – использовать этот дефолтный НС, создать/использовать НС по имени бранча, или указать свой.

Можно так в Jenkins?

Не факт – идём глянем.

Choise parameter – тут просто задаётся список предефайненных значений – нельзя будет задать своё имя НС-а:

А Multi string parameter?

Вроде как что-то аналогичное Choise parameter?

Смотрим на него:

Нет, тоже не подходит – оно просто из параметра передаст нам в переменную дженкисфайла значение из нескольких строк, а нам нужна одна string.

Значит – или таки обычный String параметр, или Choise parameter с набором уже заданных значений… Но тогда потеряем возможность создать кастомный НС…

Или… Или… Или… Мысль…

А что на счёт Boolien parameter?

Типа “поменять НС”…

Дефолтное значение “не менять” – и используем предефайненное значение bttrm-apps-dev-1-ns…

А если юзер выбирает менять – то используем имя НС как имя бранча – а имя бранча вытянем из репозитория после чекаута…

Мысль? А может быть!

Хотя снова-таки – лишаемся возможности создать кастомный НС…

А что если просто использовать тот же Choise parameter с набором уже заданных значений, но создать три значения:

• use default bm-apps-dev-ns
• use github-branch-name
• set own name

А потом в коде самого пайплайна проверять выбор, и если выбрано set own name – то просто запросить User input, и пользователь задаст имя неймспейса, который хочет создать.

Тоже не самое кошерное решение – но может сработать. Пока остановимся на нём.

Остаётся открытым вопрос про удаление НС-ов – будем думать потом 

Хотя потом может быть больно.

В конце-концов – мы спокойно можем раз в месяц удалять весь Dev-кластер, и провиженить заново – дело 20 минут и одного клика в Jenkins, а для Stage/Prod деплоев будут использоваться только жёстко заданные неймспейсы, потому там такой проблемы не будет (но это не точно).

Окей, make sense.

Что дальше?

Дальше локально сделаем:

1. создадим чарт для приложения – используем реальное, но отбранчуемся, что бы не мешать девелоперам.
2. настроим kubectl на новый Dev-кластер
3. выполним helm install

Потом пойдём делать джобу в дженкисе.

Джоба будет клонировать репозиторий с приложением, и делать helm install в нужный namespace.

А что с релизами-то? Го, почитаем Charts and Versioning.

А релиз-версии нужны судя по всему только если мы будем заливать чарты в виде архивов в свой Helm-репозиторий – в самом Кубере они никак не применяются…

Значит – пока этот вопрос отложим, потом вернёмся к chart-releaser.

Поехали тестить?

Helm test deploy

kubectl config

У меня есть новый тестовый кластер bttrm-eks-dev-1 – создаём для него конфиг.

Генерим конфиг, создаём новый контекст с именем arseniy@bttrm-eks-dev-1, см. Kubernetes: kubectl и kubeconfig — обзор файла, добавление кластера, пользователя и контекста:

aws --profile arseniy eks update-kubeconfig --name bttrm-eks-dev-1 --alias arseniy@bttrm-eks-dev-1
Added new context arseniy@bttrm-eks-dev-1 to /home/setevoy/.kube/config

Создаём тестовый чарт:

cd /tmp/
helm create deployment-testing-chart
Creating deployment-testing-chart

Helm: the server has asked for the client to provide credentials

Пробуем залить в default namespace:

helm install deployment-testing-chart --dry-run deployment-testing-chart/
Error: Kubernetes cluster unreachable: the server has asked for the client to provide credentials

WTF?

Проверяем контекст:

kk config current-context
arseniy@bttrm-eks-dev-1

(kk – алиас для kubectl в ~/.bashrc: alias kk="kubectl")

Всё верно…

А доступ есть?

kk get pod
error: You must be logged in to the server (Unauthorized)

Нет.

В автоматизации создания кластера не добавлен мой IAM user…

Что там вообще? Читаем пост AWS Elastic Kubernetes Service: RBAC-авторизация через AWS IAM и RBAC группы, вспоминаем – делал через роли, отдельных пользователей в aws-auth ConfigMap уже не добавляю.

Надо локально настроить AssumeRole.

Надеюсь я прописал в полиси этой роли доступ для моего юзера…

Пробуем – обновляем ~/.aws/config:

...
[profile iam-bttrm-eks-root]
role_arn = arn:aws:iam::534***385:role/iam-bttrm-eks-root-role
source_profile = arseniy
region = us-east-2

Удаляем созданный контекст:

kk config delete-context arseniy@bttrm-eks-dev-1
warning: this removed your active context, use "kubectl config use-context" to select a different one
deleted context arseniy@bttrm-eks-dev-1 from /home/setevoy/.kube/config

Генерим новый:

aws --profile iam-bttrm-eks-root eks update-kubeconfig --name bttrm-eks-dev-1 --alias iam-bttrm-eks-root@bttrm-eks-dev-1
Updated context iam-bttrm-eks-root@bttrm-eks-dev-1 in /home/setevoy/.kube/config

Проверяем доступ:

kk get po
NAME                                 READY   STATUS    RESTARTS   AGE
reloader-reloader-55448df76c-wdzqp   1/1     Running   0          28h

(про reloader – см. Kubernetes: ConfigMap и Secrets — auto-reload данных в подах)

Окей – возвращаемся к хельму:

helm install deployment-testing-chart --dry-run deployment-testing-chart/
NAME: deployment-testing-chart
LAST DEPLOYED: Thu May  7 20:06:44 2020
NAMESPACE: default
STATUS: pending-install
...

Найс!

Helm – deploy to  a Namespace

А что с деплоем в кастомный неймспейс?

helm install deployment-testing-chart --dry-run deployment-testing-chart/ --namespace deployment-testing-chart-ns
NAME: deployment-testing-chart
LAST DEPLOYED: Thu May  7 20:08:00 2020
NAMESPACE: deployment-testing-chart-ns
STATUS: pending-install
...

Тоже вроде ОК.

Helm и неймспейс сам создаёт? Не верится…

Попробуем реальный запуск, без --dry-run:

helm install deployment-testing-chart deployment-testing-chart/ --namespace deployment-testing-chart-ns
Error: create: failed to create: namespaces "deployment-testing-chart-ns" not found

Нет, не создаёт)

Окей – это хорошо

Гуглим – понятное дело, что до нас люди с таким уже сталкивались, например – https://github.com/helm/helm/issues/4456, и там комментарий https://github.com/helm/helm/issues/4456#issuecomment-412134651:

This is a known limitation of Helm. Helm will not do cross-namespace management, and we do not recommend setting namespace: directly in a template.
If you want to install resources in a namespace other than the default namespace, helm install –namespace=foo will install the resources in that namespace. If the namespace does not exist, it will create it.

Эээ? Так мы  ж так и делали…

Читаем ниже:

For Helm 3, the namespace creation doesn’t happen during helm install any more, so you’ll have to create that namespace ahead of time as you do today.

Ага!

И ещё ниже – https://github.com/helm/helm/issues/4456#issuecomment-607927999:

For Helm 3, the namespace creation doesn’t happen during helm install any more, so you’ll have to create that namespace ahead of time as you do today.Right now, use kubectl create namespace foo prior to helm install. When Helm 3.2.0 is released, use helm install … –create-namespace.

А у нас какая?

helm version
version.BuildInfo{Version:"v3.2.0", ...

Ага!

Пробуем:

helm install deployment-testing-chart deployment-testing-chart/ --namespace deployment-testing-chart-ns --create-namespace
NAME: deployment-testing-chart
LAST DEPLOYED: Thu May  7 20:15:38 2020
NAMESPACE: deployment-testing-chart-ns
STATUS: deployed
REVISION: 1
...

Бимба!

Проверяем НСы:

kk get ns
NAME                          STATUS   AGE
bttrm-apps-dev-1-ns           Active   28h
bttrm-workouts-dev-1-ns       Active   28h
default                       Active   28h
deployment-testing-chart-ns   Active   19s
...

Няшка.

Сервисы:

kk -n deployment-testing-chart-ns get svc
NAME                       TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)   AGE
deployment-testing-chart   ClusterIP   172.20.227.114   <none>        80/TCP    2m1s

Окей, вроде работает – можно думать за Helm chart для самого приложения.

Хотя тут можно начать наоборот с Jenkins-джобы и скрипта, и использовать тестовый чарт, а потом создавать чарт реального приложения.

Но давайте сначала всё-таки приведём в рабочий вид приложение.

Helm – создание чарта

Сейчас у нас файлы для Kubernetes лежат в отдельном репозитории devops, а код приложения – в репозитории самого приложения.

Что надо сделать – это создать чарт в репозитории с приложением – в этом репозитории будет и Dockerfile, там же будем хранить Chart.yaml.

Скрипты для Jenkins (jekinsfiles) хранятся в ещё одном отдельном репозитории для общего доступа из различных, но однотипных джоб.

What about RBAC?

Кстати. Задумался я о том, как мы будем деплоить с Jenkins и о правах доступа.

Сам Jenkins использует свою EC2 Instance Profile, которая даёт ему полный доступ к кластерам. Ту же роль использую сейчас я при AssumeRole, которую мы настроили выше в ~/.aws/config.

А что с девелоперами?

У них-то создаются отдельные RoleBinding из определённых неймспейсов, в которые им разрешается доступ, а не глобальный рутовый доступ, как у меня.

Значит – эти RoleBinding надо включить в чарт, и создавать их в тех неймспейсах, которые будут создавать при деплое чарта из Jenkins в – напомню – том числе и кастомные неймспейсы.

Как быть? Делать RBAC сабчартом?

Вопрос… Да и для самого Helm, по-хорошему, надо создавать отдельный Kubernetes ServiceAccount при создании кластера.

Хотя – зачем нам выносить доступы юзеров в отдельный чарт или сабчарт?

Там всего-то создать одну RoleBinding в нужном неймпсейсе. А “глобальная” ClusterRole создаётся при провижене самого кластера из Ansible (потом надо будет переписать на Helm, и все RBAC-ресурсы через него деплоить).

Окей – значит так и сделаем.

Создание чарта

Поехали – клонируем репозиторий, создаём каталог, создаём чарт:

mkdir k8s
cd k8s/
helm create bttrm-apps-backend
Creating bttrm-apps-backend

Удаляем шаблоны, копируем из старого репозитория:

cd bttrm-apps-backend
rm -rf templates/*
cp ~/Work/devops/projects/EKS/roles/eks/templates/bttrm-apps/* templates/

Что у нас тут есть:

ls -1 templates/
bttrm-apps-deployment.yaml
bttrm-apps-ns-ingress-hpa.yaml
bttrm-apps-secrets.yaml

Посмотрим файл деплоймента:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: bttrm-apps-EKS_ENV
  annotations:
    secret.reloader.stakater.com/reload: "bttrm-docker-secret"
spec:
  replicas: DEPLOY_REPLICAS_NUM
  strategy:
    type: RollingUpdate
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: bttrm-apps-EKS_ENV
  template:
    metadata:
      labels:
        app: bttrm-apps-EKS_ENV
    spec:
      containers:
      - name: bttrm-apps-EKS_ENV
        image: bttrm/bttrm-apps:IMAGE_TAG
        env:
        - name: CLIENT_HOST
          value: CLIENT_HOST_VAl
        - name: DATABASE_HOST
          value: DATABASE_HOST_VAL
...

Собственно, как говорилось в начале – все КАПСы вырезаются в Jenkins с помощью sed, и меняются на реальные значения, полученные из параметров джобы, а потом выполняется kubectl apply -f.

Как-то так:

...
        dir ('eks') {
            git branch: "${DEVOPS_REPO_BRANCH}", url: "${DEVOPS_REPO_URL}", credentialsId: "jenkins-github"
            def templates_path = "projects/EKS/roles/eks/templates/bttrm-apps" 
            // .env
            sed_env("$templates_path","bttrm-apps-deployment.yaml","BACKEND_HOST_VALUE","$BACKEND_HOST")
            sed_env("$templates_path","bttrm-apps-deployment.yaml","CLIENT_HOST_VAl","$CLIENT_HOST")
            sed_env("$templates_path","bttrm-apps-deployment.yaml","DEPLOY_REPLICAS_NUM","$DEPLOY_REPLICAS_NUM")
...

Ужас, правда?)

Для тестов было ОК, давайте приводить в порядок.

Сначала во всех файлах удаляем все metadata: namespace: – неймспейс будет определяться самим Хельмом.

Удаляем файл values.yaml, который сгененрировал Helm во время инициализации чарта, создаём новый файл, пустой.

Открываем в одном окне values.yaml, в другом – файл деплоймента, начинаем обновлять:

• kind: Deployment metadata: name: bttrm-apps-EKS_ENV
  испольуем {{ .Chart.Name }}
• spec: replicas: DEPLOY_REPLICAS_NUM
  вот – тут уже пора в values.yaml идти, добавляем в нём replicaCount: 2
  а в деплойменте используем replicas: {{ .Values.replicaCount }}, см. пример ниже
• selector:  matchLabels: app: bttrm-apps-EKS_ENV
  меняем на application: {{ .Chart.Name }}

Сначала думал в имя деплоймента включить .Chart.Version или .Chart.AppVersion – но тут у Хельма всё оказалось через… Печаль какую-то, т.к. задать их значения во время helm install нельзя – только во время package, см. https://github.com/helm/helm/issues/3555 (с 2018 обсуждают!).

Ладно – оставим на совести разработчиков – жираф большой, ему виднее. Пока в имени оставлю {{ .Chart.Name }} – по ходу дела посмотрим. Да и не факт, что использовать версии в имени хорошая идея.

По теме:

• 9 Best Practices and Examples for Working with Kubernetes Labels (2018 год, но интересно про лейблы и аннотации)

Пока в лейблах сделал так:

...
  selector:
    matchLabels:
      application: {{ .Chart.Name }}
  template:
    metadata:
      labels:
        application: {{ .Chart.Name }}
        version: {{ .Chart.Version }}-{{ .Chart.AppVersion }}
        managed-by: {{ .Release.Service }}-{{ .Release.Name }}
...

{{ Chart.version }} и {{ .Chart.appVersion }} будет задаваться в Jenkins, пока будем брать дефолтные значения из Chart.yaml.

Далее, для выбора Docker-образа надо в values задать имя образа и тег.

Мы сейчас хостим образы в DockerHub, но потом думаю переезжать на AWS Elastic Container Registry, поэтому сразу пусть будет с возможностью поменять.

Заполняем values.yaml – добавляем image:

replicaCount: 2
    
image:
  repository: bttrm
  name: bttrm-apps
  tag: ""

Получится строка типа bttrm/bttrm-apps:TAG, а TAG думаю формировать при сборке образа из $BUILD_NUMBER + $GIT_COMMIT, т.е. получим что-то вроде bttrm/bttrm-apps:123.67554433.

Дальше у нас идёт пачка переменных:

...
        env:
        - name: CLIENT_HOST
          value: CLIENT_HOST_VAL
        - name: DATABASE_HOST
          value: DATABASE_HOST_VAL
        - name: DB_USERNAME
          value: DB_USERNAME_VAL
...

Значения для плейсхолдеров типа CLIENT_HOST_VAL в основном будут задаваться из параметров джобы Дженкинса, но добавляем их в values тоже. Где можно – задаём дефолтные значения, где нет – просто “”.

Пока, кстати, вообще все значения можно задать в values – до Jenkins-джобы ещё будем тестить локально.

Кавычки

А что там с кавычками, кстати?

Тоже мрак)

С одной стороны – документация по созданию чарта (тыц>>>) и по переменным (тыц>>>) говорит использовать quote-функцию, которая будет “оборачивать” наши значения в кавычки.

При этом, если посмотреть файлы, сгенерированные при helm create – то там нет ни quote, ни кавычек – в большинстве случаев. Но не везде 

Например, для:

...
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
...

Кавычки есть. Почему? Потому что “составная строка” – конкатенируется из нескольких? Окей, допустим.

Но почему:

...
      containers:
        - name: {{ .Chart.Name }}
...

Без кавычек, если документация говорит их использовать? Потому что это данные из Chart.yaml, а не values.yaml?

В чём принципиальная разница?

Ну и сам YAML, как всегда – “радует”, читаем в той же документации по Values – Make Types Clear:

YAML’s type coercion rules are sometimes counterintuitive. For example, foo: false is not the same as foo: “false”. Large integers like foo: 12345678 will get converted to scientific notation in some cases.The easiest way to avoid type conversion errors is to be explicit about strings, and implicit about everything else. Or, in short, quote all strings.

Мрак!

Ладно – в values.yaml стринги заключаем в кавычки, целочисленные – без кавычек.

В файле шаблонов… Я не знаю 

Использовать quote – тогда само значение в переменных будет с кавычками. Посмотрел, как приложение запущено сейчас – без кавычек:

kk -n bttrm-apps-stage-ns describe pod bttrm-apps-stage-7c5cfd9698-tkmjp | grep CLIENT_HOST
CLIENT_HOST:                          https://test.example.com

Значит пока без quote, и без явного указания “” в шаблоне вообще.

(у нас тут Stage, который pre-Dev даже)

values.yaml

Получается такой файл:

replicaCount: 2
    
image:
  repository: "bttrm"
  name: "bttrm-apps"
  tag: ""
# backend app config
backendConfig:
  clientHost: "https://test.example.com"
  nodeEnv: "dev"
  host: "https://test.api.example.com"
  port: 3001
  database:
    host: "stage.aurora.example"
    user: "dbuser"
    password: "dbpass"
    connection: "mysql"
    port: 3306

Passwords… Secrets…

Пароли пока хардкодим – потом будем передавать из Credentials parameter в Jenkins-джобе.

А ещё лучше – таки добавить helm secrets – но это потом (добавлено – см. Helm: helm-secrets — шифрование sensitive данных с AWS KMS и деплой из Jenkins)

Секреты

Так, секреты.

В деплойменте передаём секретами, секреты создаём из файла bttrm-apps-secrets.yaml.

Сейчас он выглядит так же, как деплоймент – обрабатывается с sed в старой джобе Jenkins:

---
apiVersion: v1
kind: Secret
metadata:
  name: bttrm-app-secret
type: Opaque
stringData:
  backend-db-password: DB_PASSWORD_VAL
...

В Деплойменте маунтим из секретов:

...
    spec:
      containers:
      - name: {{ .Chart.Name }}
        image: {{ .Values.image.repository }}/{{ .Values.image.name }}:{{ .Values.image.tag }}
        env:
        ...
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: bttrm-app-backend-secret
              key: backend-db-password
...

Обновляем секрет – передаём из values:

--- 
apiVersion: v1
kind: Secret
metadata:
  name: bttrm-app-backend-secrets
type: Opaque
stringData:
  backend-db-password: {{ .Values.backendConfig.db.password }}
  backend-apple-cert-passphrase: {{ .Values.backendConfig.apple.certPassphrase }}
  backend-apple-sigin-key-id: {{ .Values.backendConfig.apple.signInKeyID }}

chart install

Ну и что – пробуем?

helm install --debug bttrm-apps-backend-release bttrm-apps-backend
install.go:159: [debug] Original chart version: ""
install.go:176: [debug] CHART PATH: /home/setevoy/Work/landing-backend/k8s/bttrm-apps-backend
client.go:108: [debug] creating 6 resource(s)
Error: Deployment in version "v1" cannot be handled as a Deployment:
v1.Deployment.Spec: v1.DeploymentSpec.Template: v1.PodTemplateSpec.Spec: v1.PodSpec.Containers: []v1.Container: v1.Container.Env: []v1.EnvVar: v1.EnvVar.Value:
ReadString: expects " or n, but found 3, error found in #10 byte of ...|,"value":3001}

Ах ты ж…

Вот честно – я тут очень матерился.

Может я не догоняю чего-то, но ты же мне везде в документации говоришь, что Integer без кавычек кушаешь нормально?

Что ж ты теперь ругаешься на цифры?

Про то, как Go вообще ошибки выводит промолчим – в них часто сложно что-то понять.

Но тут в принципе видно значение, вызвавшее ошибку – 3001:

v1.PodSpec.Containers: []v1.Container: v1.Container.Env: []v1.EnvVar: v1.EnvVar.Value: ReadString: expects ” or n, but found 3, error found in #10 byte of …|,”value”:3001}

Непонятно, конечно, где именно – но так как порты в деплойменте встречаются не так часто – то просто добавляем кавычки для всех, меняем:

...
        - name: DB_PORT
          value: {{ .Values.backendConfig.port }} 
...

На:

...
        - name: DB_PORT
          value: {{ .Values.backendConfig.db.port | quote }}
...

При этом в ports: - containerPort: на кавычки он ругается.

А в livenessProbe: port: при --dry-run не ругается. А при install – ругается.

Рукалицо. Ладно.

Деплоим ещё раз:

helm install --debug bttrm-apps-backend-release bttrm-apps-backend/
install.go:159: [debug] Original chart version: ""
install.go:176: [debug] CHART PATH: /home/setevoy/Work/landing-backend/k8s/bttrm-apps-backend
client.go:108: [debug] creating 6 resource(s)
NAME: bttrm-apps-backend-release
LAST DEPLOYED: Sun May 10 14:35:37 2020
NAMESPACE: default
STATUS: deployed
REVISION: 1
...

Йай!

Проверяем:

helm ls
NAME                    NAMESPACE       REVISION        UPDATED                                         STATUS          CHART                   APP VERSION
bttrm-apps-backend-release   default         1               2020-05-10 14:35:37.364401788 +0300 EEST        deployed        bttrm-apps-backend-0.1.0     1.16.0

Ну – бимба!

Оно 100% не работает, но нам важен сам файкт, что оно задеплоилось:

kk get pod
NAME                                 READY   STATUS    RESTARTS   AGE
bttrm-apps-backend-c4d8f8c5d-98vd2   1/1     Running   0          54s
bttrm-apps-backend-c4d8f8c5d-v6slt   1/1     Running   0          54s
...

Хорошо.

Удаляем, передеплоим в нормальный НС:

helm uninstall bttrm-apps-backend-release
release "bttrm-apps-backend-release" uninstalled

Деплоим ещё раз, указываем --create-namesapce:

helm install bttrm-apps-backend-release bttrm-apps-backend/ --namespace bttrm-apps-dev-1-ns --create-namespace
NAME: bttrm-apps-backend-release
LAST DEPLOYED: Sun May 10 14:45:23 2020
NAMESPACE: bttrm-apps-dev-1-ns
STATUS: deployed
REVISION: 1
TEST SUITE: None

Проверяем:

kk -n bttrm-apps-dev-1-ns get po
NAME                                READY   STATUS    RESTARTS   AGE
bttrm-apps-backend-6c54d5c676-5j6mc   0/1     Pending   0          47s
bttrm-apps-backend-6c54d5c676-vchvh   0/1     Pending   0          47s

Супер, но почему Pending?

Что-то с реквестами, наверно?

Глянем events:

kk -n bttrm-apps-dev-1-ns get event
LAST SEEN   TYPE      REASON                         OBJECT                                      MESSAGE
7s          Warning   FailedScheduling               pod/bttrm-apps-backend-6c54d5c676-5j6mc       0/8 nodes are available: 8 Insufficient cpu.
10s         Normal    NotTriggerScaleUp              pod/bttrm-apps-backend-6c54d5c676-5j6mc       pod didn't trigger scale-up
(it wouldn't fit if a new node is added): 4 Insufficient cpu

А почему?

В values.yaml 500 CPU requests, WorkerNodes у нас на ЕС2 t3.medium – у каждого 2000 CPU юнитов…

Проверим реквесты:

kk -n bttrm-apps-dev-1-ns describe pod bttrm-apps-backend-6c54d5c676-5j6mc
Name:           bttrm-apps-backend-6c54d5c676-5j6mc
Namespace:      bttrm-apps-dev-1-ns
...
Host Port:  0/TCP
Requests:
cpu:      500
...

Да, вроде всё верно.

Или реквесты криво описал…

Что там… Как они задаются вообще, где дока?

Вот тут вроде было толково – https://cloud.google.com/blog/products/gcp/kubernetes-best-practices-resource-requests-and-limits.

Хм…

Кавычки и m?

Редактируем values – вместо 500 указываем “500m”:

...
resources:
  requests:
    cpu: "500m"
...

И добавим quote в деплоймент:

...

        resources:

          requests:

            cpu: {{ .Values.resources.requests.cpu | quote }} 

...

Пробуем:

helm upgrade bttrm-apps-backend-release bttrm-apps-backend/ --namespace bttrm-apps-dev-1-ns

Release "bttrm-apps-backend-release" has been upgraded. Happy Helming!

NAME: bttrm-apps-backend-release

LAST DEPLOYED: Sun May 10 14:54:57 2020

NAMESPACE: bttrm-apps-dev-1-ns

STATUS: deployed

REVISION: 2

TEST SUITE: None

Евенты:

kk -n bttrm-apps-dev-1-ns get event

LAST SEEN   TYPE      REASON                         OBJECT                                      MESSAGE

47s         Normal    Scheduled                      pod/bttrm-apps-backend-69d74849df-nvtt2       Successfully assigned bttrm-apps-dev-1-ns/bttrm-apps-backend-69d74849df-nvtt2 to ip-10-3-33-123.us-east-2.compute.internal

15s         Warning   FailedMount                    pod/bttrm-apps-backend-69d74849df-nvtt2       MountVolume.SetUp failed for volume "apple-keys" : secret "apple-keys" not found

15s         Warning   FailedMount                    pod/bttrm-apps-backend-69d74849df-nvtt2       MountVolume.SetUp failed for volume "apple-certificates" : secret "apple-certificates" not found

47s         Normal    SuccessfulCreate               replicaset/bttrm-apps-backend-69d74849df      Created pod: bttrm-apps-backend-69d74849df-nvtt2

...

Ага!

Всё создалось.

Теперь поды не стартуют, потому что не файлов сертификатов для Apple – но это уже детали, сейчас их создадим.

Helm secrets from files

Добавим файлы сертификата – в Jenkins они будут маунтиться из Credentials типа Secret file, тут добавляем в текущий репозиторий:

ll bttrm-apps-be/secrets/

total 12

-rw-r--r-- 1 setevoy setevoy  258 May 10 17:32 AppleAuth.key.p8

-rw-r--r-- 1 setevoy setevoy 3088 May 10 17:27 ApplePay.crt.pem

-rw-r--r-- 1 setevoy setevoy 2006 May 10 17:28 ApplePay.key.pem

Добавляем в ../.gitignore репозитория и в .helmignore чарта:

...

k8s/bttrm-apps-backend/secrets/

Обновляем bttrm-apps-secrets.yaml – используем Files, см https://helm.sh/docs/chart_template_guide/accessing_files/:

...

---

apiVersion: v1

kind: Secret

metadata:

  name: apple-certificates

type: Opaque

data:

  ApplePay.crt.pem: {{ .Files.Get "secrets/ApplePay.crt.pem" | b64enc }}

  ApplePay.key.pem: {{ .Files.Get "secrets/ApplePay.key.pem" | b64enc }}

---

apiVersion: v1

kind: Secret

metadata:

  name: apple-key

type: Opaque

data:

  AppleAuth.key.p8: {{ .Files.Get "secrets/AppleAuth.key.p8" | b64enc }}

Запускаем:

helm upgrade bttrm-apps-be-release bttrm-apps-be/ --namespace bttrm-apps-dev-1-ns

Release "bttrm-apps-be-release" has been upgraded. Happy Helming!

NAME: bttrm-apps-be-release

LAST DEPLOYED: Sun May 10 17:36:47 2020

NAMESPACE: bttrm-apps-dev-1-ns

STATUS: deployed

REVISION: 4

TEST SUITE: None

Проверяем секреты:

kk -n bttrm-apps-dev-1-ns get secret

NAME                                          TYPE                                  DATA   AGE

apple-certificates                            Opaque                                2      37s

apple-key                                     Opaque                                1      37s

Но поды серты не увидели, и не запустилиись, так и будут висеть в FailedMount.

Пересоздаём их – вызываем upgrade с --recreate-pods:

helm upgrade bttrm-apps-be-release bttrm-apps-be/ --namespace bttrm-apps-dev-1-ns --recreate-pods

Flag --recreate-pods has been deprecated, functionality will no longer be updated. Consult the documentation for other methods to recreate pods

Release "bttrm-apps-be-release" has been upgraded. Happy Helming!

NAME: bttrm-apps-be-release

LAST DEPLOYED: Sun May 10 17:39:39 2020

NAMESPACE: bttrm-apps-dev-1-ns

STATUS: deployed

REVISION: 5

TEST SUITE: None

Проверяем:

helm -n bttrm-apps-dev-1-ns ls

NAME                    NAMESPACE               REVISION        UPDATED                                         STATUS          CHART                   APP VERSION

bttrm-apps-be-release   bttrm-apps-dev-1-ns     2               2020-05-10 17:44:56.505478002 +0300 EEST        deployed        bttrm-apps-be-0.1.0     1.16.0

kk -n bttrm-apps-dev-1-ns get pod

NAME                                READY   STATUS    RESTARTS   AGE

bttrm-apps-be-dp-6f86d5c7d7-k4rjm   1/1     Running   0          2m

bttrm-apps-be-dp-6f86d5c7d7-ztcvp   1/1     Running   0          83s

Тут готово.

.dockerconfigjson

Сейчас в секретах файла bttrm-apps-secrets.yaml значение для .dockerconfigjson задан хардкодом:

--- 

apiVersion: v1

kind: Secret

metadata:

  creationTimestamp: null

  name: bttrm-docker-secret

type: kubernetes.io/dockerconfigjson

data:

  .dockerconfigjson: eyJhdXRo[...]

...

Находим пример в документации – Creating Image Pull Secrets.

Обновляем values.yaml – в блок image добавляем registry, username и password, пароль позже будем передавать из Jenkins:

...

image:

  registry: "docker.io" 

  username: "username"

  password: "pass"

  repository: "project"

  name: "bttrm-apps"

  tag: "120"

...

Создаём templates/_helpers.tpl, см. Nested template definitions.

Копируем функцию из примера в Creating Image Pull Secrets, меняем .Values.imageCredentials на наш .Values.image:

{{- define "imagePullSecret" }}

{{- printf "{"auths": {"%s": {"auth": "%s"}}}" .Values.image.registry (printf "%s:%s" .Values.image.username .Values.image.password | b64enc) | b64enc }}

{{- end }}

Обновляем секреты – вместо хардкод-строки в base64 вызываем этот самый {{ template "imagePullSecret" . }}:

--- 

apiVersion: v1

kind: Secret

metadata:

  creationTimestamp: null

  name: bttrm-docker-secret

type: kubernetes.io/dockerconfigjson

data:

  .dockerconfigjson: {{ template "imagePullSecret" . }} 

...

Передеплоиваем для проверки, и если всё ОК – то можно приступать в Jenkins.

Jenkins

Поехали к сиаю.

Что нам надо?

Сначала давай подумаем про шаги, которые надо выполнить в джобе:

1. склонировать репозиторий приложения с helm-чартом, кодом приложения и докерфайлом
2. билд образа – тегаем Jenkins $BUILD_NUMBER + $GIT_COMMIT
3. docker push собранного образа, пока в DockerHub
4. упаковка релиза + задать номера релиза и AppVersion, AppVersion == Docker Tag. т.е. $BUILD_NUMBER + $GIT_COMMIT
   1. позже – релиз в Гитхаб
5. сгенерить кубконфиг
6. выполнить helm install

Версинирование

Тут, конечно, по желанию каждого.

Мне пока в голову пришла такая схема:

• chart release number == Jenkins $BUILD_NUMBER джобы
• AppVersion == $BUILD_NUMBER + $GIT_COMMIT
• Docker image tag == $BUILD_NUMBER + $GIT_COMMIT

Неймспейсы опять (снова?)

Что там с НС-ами было?

Давайте вспоминать – день четвёртый, на самом деле.

Хочется давать на выбор три варианта:

1. дефолтный неймпейс – APP_NAME + CLUSTER_ENV + “NS”, т.е. поулчим bttrm-apps-dev-1ns
2. неймспейс с именем бранча – APP_NAME + CLUSTER_ENV + GIT_BRANCH_NAME + “NS”, т.е. bttrm-apps-dev-1-WLIOS-5848-Projects-deployments
3. кастомный неймспейс, задаётся юзером

Есть сомнения по второму пункту – bttrm-apps-dev-1-WLIOS-5848-Projects-deployments – не слишком ли длинно?