К содержимому
Войти

Go Road Map

⚙️ Конфигурация, миграции и graceful shutdown

Сервис на Go почти всегда собран одинаково: при старте он читает конфиг, накатывает или проверяет схему базы, а при деплое получает SIGTERM и должен уйти, не оборвав чужие запросы. Эти три вещи живут в main.go, и на них держится спокойный деплой. На собеседовании про них спрашивают в связке: откуда сервис берёт настройки, как ты катишь миграции, если реплик несколько, и что происходит с запросом, который пришёл за секунду до остановки пода

🧠 Как это устроено

Конфиг из окружения

Один и тот же образ едет на стенд и в прод, а отличаются только настройки. Поэтому их передают переменными окружения, как советует The Twelve-Factor App. Файл с паролем в образ не попадает, а смена адреса базы не требует пересборки

Первое правило: конфиг читают один раз в main в структуру и передают дальше явно. os.Getenv в глубине пакета repo прячет зависимость, и никто не знает, какие переменные нужны сервису. Второе правило: сервис с плохим конфигом падает сразу при старте и называет все ошибки одним сообщением. Упасть через час на первом заказе, потому что SMTP_PORT=twenty-five превратился в ноль, хуже

Чем читать:

СпособКогда подходитЧем платишь
os.LookupEnv + strconvтри-пять переменныхразбор, умолчания и проверки пишешь руками
caarlos0/env (v11)типичный сервистеги на структуре, ещё одна зависимость
spf13/viperнужны файлы, флаги и слежение за изменениямитянет YAML, TOML, fsnotify и afero, а ключи ищет по строкам

os.Getenv не отличает пустую переменную от отсутствующей, а os.LookupEnv отличает: вторым значением он возвращает ok

Миграции

Изменения схемы лежат в репозитории файлами по версиям: 00001_create_orders.sql, 00002_orders_user_idx.sql. Инструмент хранит в служебной таблице, какие версии уже применены, и при запуске докатывает недостающие по порядку. В Go чаще всего берут goose (pressly/goose, сейчас v3.29) и golang-migrate (golang-migrate/migrate, v4.20). Устроены они похоже, но отличаются в мелочах, которые всплывают ровно тогда, когда миграция упала

Чтоgoosegolang-migrate
Файлыодин файл с секциями -- +goose Up и -- +goose Downпара 000001_x.up.sql и 000001_x.down.sql
Транзакциякаждая миграция в своей транзакции, отключается -- +goose NO TRANSACTIONсам не оборачивает, BEGIN и COMMIT пишешь в файле
Служебная таблицаgoose_db_version, история примененийschema_migrations, одна строка: версия и флаг dirty
Если миграция упалаверсия не записана, исправил и запустил сновабаза помечена dirty, дальше только через force
Несколько репликблокировка включается опцией WithSessionLockerдрайвер Postgres сам берёт pg_advisory_lock

Обе утилиты берут файлы из бинарника через embed, и миграции едут вместе с сервисом

Запускать миграции можно двумя способами. Сервис накатывает их сам при старте: просто, но нужна блокировка, иначе две реплики возьмутся за одну версию, а долгая миграция не даст поду пройти startup-пробу. Или отдельный шаг перед выкаткой, Job в Kubernetes или шаг в CI: права на DDL есть только у мигратора, и упавшая миграция останавливает деплой раньше, чем новый код увидел трафик

В обоих случаях какое-то время старый код работает с новой схемой: rolling update меняет поды по одному, а откат возвращает старый код на уже изменённую базу. Поэтому миграция обязана быть совместима с предыдущей версией кода. Переименование колонки делают за несколько релизов: добавить новую колонку, писать в обе, перенести данные, переключить чтение, и только потом, в отдельном релизе, удалить старую. Этот подход называют expand/contract

Что происходит при остановке пода

Когда Kubernetes останавливает под, события идут так:

  1. Под помечается Terminating. Параллельно контроллер убирает его из EndpointSlice сервиса, а kube-proxy и ингресс узнают об этом не мгновенно
  2. Если у контейнера есть preStop-хук, kubelet выполняет его
  3. Процесс получает SIGTERM
  4. Если процесс не вышел за terminationGracePeriodSeconds (по умолчанию 30 секунд, и preStop входит в это время), приходит SIGKILL

Из первого шага следует, что в первые секунды после SIGTERM на под ещё приходят новые запросы, и закрытый порт ответит им ошибкой соединения. Поэтому сервис сначала перестаёт быть ready, ждёт несколько секунд и только потом закрывает порт. Ту же паузу дают preStop с действием sleep. Пробы и выкатку без простоя разбирает страница «Пробы, ресурсы и деплой без простоя» в модуле «Docker, Kubernetes и наблюдаемость»

Что делает Server.Shutdown

srv.Shutdown(ctx) закрывает слушающие сокеты, закрывает простаивающие keep-alive соединения и ждёт, пока активные запросы закончатся. Ответы на запросы, которые дорабатывают во время остановки, получают заголовок Connection: close, и следующий запрос клиент отправит уже по новому соединению

Чего он не делает:

  • не отменяет контекст запросов. Хендлер, который ждёт базу 40 секунд, будет ждать дальше. Ограничивает это только ctx самого Shutdown: когда он истёк, Shutdown возвращает context deadline exceeded, а соединения так и остаются открытыми. Оборвать их можно через srv.Close(), он же отменит контексты запросов
  • не ждёт захваченные соединения. WebSocket после Hijack серверу больше не принадлежит. Закрывать такие соединения придётся самому, а сигнал о старте остановки даёт srv.RegisterOnShutdown
  • не держит ListenAndServe. Тот сразу возвращает http.ErrServerClosed, поэтому main должен ждать возврата самого Shutdown

Таймауты самого сервера разобраны на странице про HTTP-сервер. У gRPC ту же работу делает GracefulStop, его разбирает страница про gRPC-сервис

Выключают в порядке, обратном зависимостям: трафик, HTTP-запросы, консьюмеры и воркеры, и последним пул соединений к базе. Хендлеры пользуются пулом до последней секунды, и если закрыть его первым, запросы в полёте получат ошибку closed pool

🛠️ На практике

Конфиг в структуре

type Config struct {
	HTTPAddr        string        `env:"HTTP_ADDR" envDefault:":8080"`
	DatabaseURL     string        `env:"DATABASE_URL,required,notEmpty"`
	DrainDelay      time.Duration `env:"DRAIN_DELAY" envDefault:"5s"`
	ShutdownTimeout time.Duration `env:"SHUTDOWN_TIMEOUT" envDefault:"20s"`
	Workers         int           `env:"WORKERS" envDefault:"4"`
}

cfg, err := env.ParseAs[Config]()
if err != nil {
	log.Fatalf("config: %v", err)
}

caarlos0/env собирает ошибки всех полей в одну. Вот что он вернул на запуске с WORKERS=four и SHUTDOWN_TIMEOUT=20:

config: env: parse error on field "ShutdownTimeout" of type "time.Duration":
unable to parse duration: time: missing unit in duration "20";
parse error on field "Workers" of type "int": strconv.ParseInt: parsing "four": invalid syntax

required проверяет только то, что переменная есть. Пустая строка DATABASE_URL= его проходит, и сервис стартует без адреса базы. Пустоту ловит notEmpty, поэтому для обязательных полей ставят оба

Миграции из бинарника через goose

//go:embed migrations/*.sql
var migrations embed.FS

func migrate(ctx context.Context, db *sql.DB) error {
	sub, _ := fs.Sub(migrations, "migrations")
	locker, err := lock.NewPostgresSessionLocker()
	if err != nil {
		return err
	}
	p, err := goose.NewProvider(goose.DialectPostgres, db, sub, goose.WithSessionLocker(locker))
	if err != nil {
		return err
	}
	_, err = p.Up(ctx)
	return err
}

db здесь из database/sql: с pgx его открывают через драйвер github.com/jackc/pgx/v5/stdlib. В проверке две горутины одновременно вызвали Up на пустой базе. С блокировкой первая применила обе миграции за 27 мс, вторая подождала около секунды, увидела, что всё применено, и вышла без ошибки

Postgres не строит индекс CONCURRENTLY внутри транзакции, а goose по умолчанию открывает её на каждую миграцию:

partial migration error (type:sql,version:2): ERROR: CREATE INDEX CONCURRENTLY
cannot run inside a transaction block (SQLSTATE 25001)

Первая миграция при этом применилась и записалась, вторая нет. Лечится одной строкой в начале файла:

-- +goose NO TRANSACTION
-- +goose Up
CREATE INDEX CONCURRENTLY orders_user_id_idx ON orders (user_id);

Без транзакции упавшая посередине миграция оставит базу в промежуточном состоянии, поэтому в такой файл кладут одну команду

Dirty в golang-migrate

В проверке файл для golang-migrate содержал CREATE TABLE users и индекс с опечаткой в имени колонки. Первый Up вернул column "emial" does not exist, второй — Dirty database version 1. Fix and force version. Таблицы users в базе при этом не оказалось: драйвер отправил файл одним запросом, и Postgres выполнил его в одной неявной транзакции, которая откатилась целиком. А schema_migrations всё равно хранит 1 | t

Поэтому dirty значит одно: инструмент не знает, что сейчас в базе. Применилась ли миграция наполовину, целиком или никак, видно только по схеме. Сначала смотрят на реальную схему, потом ставят migrate force <версия> той миграции, которая применена целиком, и только потом запускают up с исправленным файлом

main, который выключается правильно

Go · Конфиг, readiness, остановка HTTP и воркеров

func main() {
	cfg, err := env.ParseAs[Config]()
	if err != nil {
		log.Fatalf("config: %v", err)
	}

	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, os.Interrupt)
	defer stop()

	pool, err := pgxpool.New(context.Background(), cfg.DatabaseURL)
	if err != nil {
		log.Fatalf("db: %v", err)
	}
	defer pool.Close() // defer выполняются в обратном порядке: пул закроется последним

	var ready atomic.Bool
	ready.Store(true)
	mux := http.NewServeMux()
	mux.HandleFunc("GET /readyz", func(w http.ResponseWriter, r *http.Request) {
		if !ready.Load() {
			http.Error(w, "shutting down", http.StatusServiceUnavailable)
			return
		}
		w.Write([]byte("ok"))
	})

	// у фоновой работы свой контекст: его отменяют после остановки HTTP
	wctx, cancelWorkers := context.WithCancel(context.Background())
	var workers sync.WaitGroup
	workers.Go(func() { runOutboxRelay(wctx, pool) })

	srv := &http.Server{Addr: cfg.HTTPAddr, Handler: mux, ReadHeaderTimeout: 5 * time.Second}
	go func() {
		if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
			log.Fatalf("http: %v", err) // порт занят: выходим сразу, дожидаться нечего
		}
	}()

	<-ctx.Done()
	stop() // теперь второй SIGTERM или Ctrl+C завершит процесс сразу
	log.Printf("shutting down: %v", context.Cause(ctx))

	ready.Store(false)         // readiness-проба отвечает 503, под убирают из балансировки
	time.Sleep(cfg.DrainDelay) // ждём, пока об этом узнают все, кто шлёт трафик

	sctx, cancel := context.WithTimeout(context.Background(), cfg.ShutdownTimeout)
	defer cancel()
	if err := srv.Shutdown(sctx); err != nil {
		log.Printf("http shutdown: %v", err)
		srv.Close() // оборвать то, что не успело
	}

	cancelWorkers()
	workers.Wait()
}

5 секунд паузы и 20 на Shutdown укладываются в 30 секунд terminationGracePeriodSeconds с запасом. С Go 1.26 context.Cause на контексте из signal.NotifyContext говорит, какой сигнал пришёл: в логе будет shutting down: terminated signal received

В проверке сервер с хендлером на 2 секунды получал SIGTERM через 300 мс после начала запроса:

  • запрос, который уже шёл, получил 200 и Connection: close через 2,06 с, а Shutdown вернулся через 2,1 с
  • без паузы новое соединение через 300 мс после SIGTERM уже не открылось, curl вернул код 7, «не удалось подключиться». Это и получат запросы, которые балансировщик ещё не перестал слать на под
  • с паузой в 1 с /readyz отвечал 503, а обычные запросы обслуживались как раньше. Для этого пауза и нужна
  • при ShutdownTimeout в 1 с и хендлере на 3 с Shutdown вернул context deadline exceeded, Close отменил контекст хендлера, клиент получил пустой ответ
  • без вызова stop() второй SIGTERM процесс игнорирует, с ним второй сигнал завершает процесс сразу

⚠️ Где ошибаются

log.Fatal(srv.ListenAndServe()) рядом с Shutdown в горутине. ListenAndServe возвращается в момент вызова Shutdown, main выходит и забирает с собой запросы в полёте. В проверке медленный запрос оборвался через 0,36 с после старта, curl вернул код 52, «пустой ответ». main должен ждать возврата Shutdown, а не ListenAndServe

Таймаут остановки больше, чем даёт Kubernetes. ShutdownTimeout: 60s при grace period в 30 секунд не сработает никогда: раньше придёт SIGKILL. Таймаут считают от terminationGracePeriodSeconds минус пауза и preStop, и оставляют несколько секунд на закрытие пула и сброс телеметрии

Контекст сигнала в Shutdown. srv.Shutdown(ctx), где ctx пришёл из signal.NotifyContext, выглядит естественно, но этот контекст уже отменён: сигнал его и отменил. Shutdown сразу возвращает context canceled, и запросы в полёте обрываются так же, как без graceful shutdown. В проверке клиент получил пустой ответ через 0,34 с. Таймаут остановки строят от context.Background()

Пароль в логе стартового конфига. log.Printf("%+v", cfg) печатает DATABASE_URL целиком. Тип Secret с методом String() string, который возвращает ***, закрывает fmt, но не закрывает JSON-логи: slog.NewJSONHandler сериализует структуру через encoding/json, и в проверке пароль ушёл в лог открытым текстом. Секретному типу нужен ещё MarshalJSON, или логируй поля конфига по одному

Правка уже применённой миграции. Ни goose, ни golang-migrate не перечитывают файл, версия которого уже есть в служебной таблице, и в проде останется старая схема. Применённая миграция не меняется, исправление пишут следующей версией

🎯 Вопросы с собеседований

Как сделать graceful shutdown HTTP-сервера в Go?

Поймать SIGTERM через signal.NotifyContext, ListenAndServe держать в горутине, а main пусть ждёт ctx.Done(). Дальше readiness в 503 и пауза в несколько секунд, чтобы балансировщик убрал под. Потом srv.Shutdown с таймаутом от context.Background(), а если он истёк, srv.Close(). В конце остановить воркеры и закрыть пул к базе

Что делает Server.Shutdown и чего он не делает?

Закрывает слушающие сокеты и простаивающие соединения, а активные ждёт до конца запроса. Контексты запросов он не отменяет, WebSocket и другие захваченные соединения не ждёт. Если ctx истёк, он возвращает ошибку, но соединения не рвёт, это делает Close

Что происходит с подом при удалении и почему сервис не должен сразу закрывать порт?

Под помечается Terminating, выполняется preStop, процесс получает SIGTERM, а через terminationGracePeriodSeconds (по умолчанию 30 с) приходит SIGKILL. Удаление пода из EndpointSlice идёт параллельно и доходит до kube-proxy и ингресса с задержкой. Поэтому первые секунды после SIGTERM новые запросы ещё приходят. Если сразу закрыть порт, они упадут с ошибкой соединения, поэтому сначала делают паузу через readiness или preStop со sleep

Откуда сервис берёт конфигурацию и почему так?

Из переменных окружения: один образ запускается на всех стендах, отличаются только переменные, а секреты не попадают в образ и в git. Читаю их один раз в main в структуру, проверяю и при ошибке падаю сразу со списком всех проблем. Дальше конфиг передаётся явно в конструкторы, без os.Getenv внутри пакетов. В Kubernetes переменные приходят из ConfigMap и Secret

Как катить миграции, если у сервиса несколько реплик?

Либо отдельным шагом до выкатки, Job или шагом в CI, либо при старте сервиса, но с блокировкой. В goose её включает WithSessionLocker, драйвер Postgres в golang-migrate берёт pg_advisory_lock сам: одна реплика применяет миграции, остальные ждут. Отдельный шаг лучше, когда миграции долгие или когда у сервиса не должно быть прав на DDL

Как переименовать колонку без простоя?

За несколько релизов, потому что во время выкатки старый и новый код работают одновременно. Добавить новую колонку, научить код писать в обе, перенести старые данные, переключить чтение на новую, и только в следующем релизе удалить старую. Это expand/contract. Один ALTER TABLE ... RENAME COLUMN сломает поды со старым кодом, которые ещё обслуживают трафик

Что значит dirty в golang-migrate и что с ним делать?

Флаг ставится перед миграцией и снимается после успеха. Если миграция упала, флаг остаётся, и следующие запуски отказываются работать. Что на самом деле в базе, показывает только схема: в Postgres файл часто откатывается целиком. Смотрю схему, ставлю force в реально применённую версию и запускаю исправленную миграцию

📚 Что почитать

  • Server.Shutdown в net/http — что метод делает и чего не делает, из первых рук
  • Termination of Pods — порядок остановки пода, preStop и grace period в документации Kubernetes
  • README goose — аннотации в файлах миграций, NO TRANSACTION, embed и гибридная нумерация версий
  • Getting started в golang-migrate — про транзакции в файлах, блокировки и force после dirty