Сценарий 1. Новый проект

#Шаг 1. Возьмите шаблон

В репозитории лежит projects/example.yaml.disabled. Скопируйте его в projects/<имя>.yaml и уберите суффикс .disabled — он есть только для того, чтобы шаблон сам не считался проектом.

Внутри шаблона у каждого поля стоит комментарий, и часть комментариев описывает правила, которые сервис действительно проверяет. Их стоит прочитать, а не пролистать: они короче, чем ошибка, которую предотвращают.

#Шаг 2. Заполните

Вот минимальный работающий файл. Всё, что здесь есть, обязательно; всё, чего нет, можно не писать.

project: acme                    # имя группы в GitLab и основа для всех производных имён
display_name: Acme

envs:
  prod:
    cluster: talos-hetzner-helsinki
    namespace: acme
  staging:
    cluster: microk8s-hoster-bishkek
    namespace: acme

members:
  - person: [email protected]
    role: owner

platforms:
  gitlab:
    group: acme

datastores:
  postgres:
    databases: [acme_db]

services:
  - name: api
    tier: backend
    stack: python
    datastores: [postgres]
    hostnames:
      staging: [acme-api.geekstudio.kg]
    paths: ["/"]

Разберём то, о чём чаще всего спрашивают.

envs — окружение это пара «кластер плюс namespace». Двум окружениям нельзя иметь одинаковую пару: это отдельная проверка, и она существует потому, что такая ошибка приводит к тому, что два окружения молча пишут друг в друга.

members — тот, кто будет владеть проектом. Почта обязана быть в people.yaml, иначе проверка не пройдёт.

services — здесь tier это backend, frontend или mobile, а stack определяет, какой каркас положат в репозиторий: сегодня есть python, nodejs, golang, react, flutter.

Порт не указан, и это правильно. Он выводится сам: бэкенды получают номера с 8000 в порядке объявления, react-фронтенды 8080. Указывать порт стоит только если сервис по-настоящему слушает другой — тогда вы пишете факт, а не повторяете значение по умолчанию.

hostnames есть только для staging. Это осознанно, смотрите ниже.

#Шаг 3. Что делает сервис публичным

Флага «сделать публичным» не существует. Публичным сервис делает запись в hostnames, и ничего кроме неё.

Обратная сторона: имя хоста никто не придумывает за вас. Сервис не создаёт ни DNS-запись, ни правило на входе. Если вы написали hostnames, а зона не наша или запись не сделана, сервис так и скажет — он не станет изобретать адрес.

Для продакшена это обычно означает отдельный разговор про домен. Поэтому в примере выше есть staging и нет prod: staging живёт под geekstudio.kg, которым мы управляем, и работает сразу.

paths занимает префикс на хосте, а не весь хост. Делить один хост между сервисами здесь нормально. Нельзя только двум сервисам занять одну и ту же пару «хост плюс префикс», и нельзя двум сервисам сидеть на одном хосте, если ни один не указал префикс — тогда оба оказываются на /.

#Шаг 4. Проверьте и откройте merge request

Дальше как в разделе про то, как проходит изменение: предпросмотр, проверка, мерж, пять минут.

#Что появится

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

#Чего не появится, и почему это правильно

Секретов для продакшена. Их закладывает человек отдельным шагом. Ключ-заглушка, попавший в продакшен, — не меньшая проблема, чем отсутствующий ключ, а большая: он выглядит настроенным.

DNS-записи в зоне, которой мы не управляем. Сервис откажется и назовёт причину.

Ничего для окружения с gated: true. Про это стоит прочитать отдельно, потому что название обманывает.

#Одна ловушка, на которую стоит потратить минуту сейчас

Сервис нельзя назвать backend — и ещё двадцатью именами, совпадающими с ключами файла настроек (image, port, worker, service, route, probes и так далее). Имя сервиса и ключ настроек попадают в одно пространство имён, и под поднимается с образом, имя которого не имя.

Запоминать список не нужно: проверка не пропустит такое имя и перечислит все запрещённые в сообщении. Полный список есть в разделе про ловушки.

Назовите api, web, или по делу — как сервис называется в разговоре.