⚙️ Конфигурация, миграции и 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). Устроены они похоже, но отличаются в мелочах, которые всплывают ровно тогда, когда миграция упала
| Что | goose | golang-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 останавливает под, события идут так:
- Под помечается
Terminating. Параллельно контроллер убирает его из EndpointSlice сервиса, а kube-proxy и ингресс узнают об этом не мгновенно - Если у контейнера есть
preStop-хук, kubelet выполняет его - Процесс получает
SIGTERM - Если процесс не вышел за
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 syntaxrequired проверяет только то, что переменная есть. Пустая строка 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