Kurs NestJS · Moduł 9: Deployment i infrastruktura

Blue-Green Deployment i Zero-Downtime - sztuka bezprzerwowej zmiany warty

9 min czytania ·
W tej lekcji6

Mistrzu strategii! Senator Cicero powiada: „Imperium nigdy nie śpi, a drogi muszą być zawsze otwarte”. Tymczasem każde wdrożenie oznacza pół minuty błędów 502, bo stary proces już zgasł, a nowy jeszcze nie wstał. Rzymskie legiony zmieniały wartę bez pozostawiania murów bez obrony - aplikacje też muszą aktualizować się bez przerw w działaniu.

Blue-Green Deployment to technika, w której utrzymujemy dwa identyczne środowiska produkcyjne (blue i green). W danym momencie tylko jedno obsługuje ruch, a drugie przyjmuje nową wersję. Przełączenie następuje natychmiast, bez przestojów.

Koncepcja Blue-Green Deployment

Wyobraź sobie dwie bramy miasta. Blue jest otwarta i obsługuje podróżnych, a w green strażnicy montują nowe fortyfikacje. Gdy green jest gotowa, ruch przechodzi na nią. Konfigurację obu slotów opisują dwa interfejsy:

// src/deployment/blue-green.config.ts
interface DeploymentSlot {
  name: 'blue' | 'green';
  port: number;
  version: string;
  status: 'active' | 'standby' | 'deploying';
  healthCheckUrl: string;
  startedAt: Date;
}

interface BlueGreenConfig {
  activeSlot: 'blue' | 'green';
  slots: {
    blue: DeploymentSlot;
    green: DeploymentSlot;
  };
  loadBalancerUrl: string;
  healthCheckInterval: number; // ms
  healthCheckRetries: number;
  rollbackTimeout: number;    // ms
}

const deploymentConfig: BlueGreenConfig = {
  activeSlot: 'blue',
  slots: {
    blue: {
      name: 'blue',
      port: 3001,
      version: '2.3.0',
      status: 'active',
      healthCheckUrl: 'http://blue.imperium.internal:3001/health',
      startedAt: new Date(),
    },
    green: {
      name: 'green',
      port: 3002,
      version: '2.4.0',
      status: 'standby',
      healthCheckUrl: 'http://green.imperium.internal:3002/health',
      startedAt: new Date(),
    },
  },
  loadBalancerUrl: 'http://lb.imperium.internal',
  healthCheckInterval: 5000,
  healthCheckRetries: 3,
  rollbackTimeout: 30000,
};

activeSlot wskazuje bramę z ruchem, a przełączenie to zmiana celu w load balancerze. Rollback polega na przełączeniu z powrotem, bo stara wersja wciąż działa. Ceną są podwójne zasoby, a długie połączenia, np. WebSocket, trzeba świadomie przenieść.

Rolling Updates

Rolling update stopniowo zastępuje stare instancje nowymi, jak zmiana warty centurionów, dzięki czemu część instancji zawsze obsługuje ruch:

// src/deployment/rolling-update.service.ts
import { Injectable, Logger } from '@nestjs/common';

interface Instance {
  id: string;
  version: string;
  status: 'running' | 'updating' | 'ready' | 'failed';
  port: number;
}

@Injectable()
export class RollingUpdateService {
  private readonly logger = new Logger(RollingUpdateService.name);

  async performRollingUpdate(
    instances: Instance[],
    newVersion: string,
    maxUnavailable: number = 1,
  ): Promise<void> {
    this.logger.log(
      `Rozpoczynam rolling update do wersji ${newVersion}`
    );
    this.logger.log(
      `Instancje: ${instances.length}, max niedostępnych: ${maxUnavailable}`
    );

    // Aktualizuj instancje partiami - cała partia naraz
    for (let i = 0; i < instances.length; i += maxUnavailable) {
      const batch = instances.slice(i, i + maxUnavailable);
      const results = await Promise.all(
        batch.map((instance) => this.updateInstance(instance, newVersion)),
      );

      // Nieudana instancja zatrzymuje cały rollout
      if (results.includes(false)) {
        throw new Error(`Rolling update do wersji ${newVersion} zatrzymany`);
      }
    }
  }

Promise.all aktualizuje całą partię naraz. Pierwsza wersja miała pętlę z await wewnątrz partii, więc mimo parametru maxUnavailable zawsze wyłączała jedną instancję. Nieudana instancja zatrzymuje teraz cały rollout, zamiast psuć kolejne - w teście z sześcioma instancjami dwie ostatnie zostały nietknięte.

Każda instancja przechodzi pięć kroków w stałej kolejności:

  private async updateInstance(instance: Instance, newVersion: string): Promise<boolean> {
    instance.status = 'updating';
    this.logger.log(`Aktualizuję instancję ${instance.id}...`);

    // 1. Wyłącz instancję z load balancera
    await this.removeFromLoadBalancer(instance);

    // 2. Poczekaj aż bieżące requesty się zakończą
    await this.drainConnections(instance);

    // 3. Zaktualizuj do nowej wersji
    await this.deployNewVersion(instance, newVersion);

    // 4. Sprawdź health check
    const healthy = await this.waitForHealthy(instance);

    if (healthy) {
      instance.status = 'running';
      instance.version = newVersion;
      // 5. Dodaj instancję z powrotem do load balancera
      await this.addToLoadBalancer(instance);
      this.logger.log(`Instancja ${instance.id} zaktualizowana`);
      return true;
    }

    instance.status = 'failed';
    this.logger.error(
      `Instancja ${instance.id} - rollback!`
    );
    await this.rollback(instance);
    return false;
  }

Instancja znika z load balancera, oddaje trwające żądania, dostaje nową wersję, przechodzi health check i dopiero wtedy wraca do puli.

Metody pomocnicze to szkielet do podłączenia pod Twoją infrastrukturę:

  private async removeFromLoadBalancer(instance: Instance) {
    // Usuń instancję z puli load balancera
  }

  private async drainConnections(instance: Instance) {
    // Poczekaj aż aktywne połączenia się zakończą (graceful)
  }

  private async deployNewVersion(
    instance: Instance, version: string
  ) {
    // Wdrożenie nowej wersji na instancji
  }

  private async waitForHealthy(instance: Instance): Promise<boolean> {
    const maxRetries = 10;
    for (let i = 0; i < maxRetries; i++) {
      try {
        // Sprawdź endpoint /health/ready nowej wersji
        const response = await fetch(`http://localhost:${instance.port}/health/ready`, {
          signal: AbortSignal.timeout(2000),
        });
        if (response.ok) return true;
      } catch {
        // Instancja jeszcze nie odpowiada
      }
      await new Promise(r => setTimeout(r, 2000)); // przerwa po każdej próbie
    }
    return false;
  }

  private async addToLoadBalancer(instance: Instance) {
    // Dodaj instancję z powrotem do puli
  }

  private async rollback(instance: Instance) {
    // Przywróć poprzednią wersję i dodaj instancję z powrotem do puli
  }
}

waitForHealthy() odpytuje /health/ready z limitem czasu i czeka po każdej próbie. Pierwsza wersja czekała tylko po wyjątku, więc dziesięć nieudanych odpowiedzi mijało w ułamku sekundy.

Health Check-based Deployment

Health checki to zwiadowcy Imperium - sprawdzają, czy nowa fortyfikacja jest gotowa, zanim otworzymy bramy:

// src/health/deployment-health.controller.ts
import { Controller, Get } from '@nestjs/common';
import {
  HealthCheck, HealthCheckService,
  MongooseHealthIndicator, MemoryHealthIndicator,
  DiskHealthIndicator,
} from '@nestjs/terminus';

@Controller('health')
export class DeploymentHealthController {
  constructor(
    private health: HealthCheckService,
    private mongoose: MongooseHealthIndicator,
    private memory: MemoryHealthIndicator,
    private disk: DiskHealthIndicator,
  ) {}

  // Liveness - czy aplikacja żyje?
  @Get('live')
  @HealthCheck()
  checkLiveness() {
    return this.health.check([
      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024),
    ]);
  }

  // Readiness - czy gotowa na ruch?
  @Get('ready')
  @HealthCheck()
  checkReadiness() {
    return this.health.check([
      () => this.mongoose.pingCheck('mongodb'),
      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024),
      () => this.disk.checkStorage('disk', {
        thresholdPercent: 0.9, path: '/',
      }),
    ]);
  }

  // Startup - czy aplikacja wystartowała poprawnie?
  @Get('startup')
  @HealthCheck()
  checkStartup() {
    return this.health.check([
      () => this.mongoose.pingCheck('mongodb'),
    ]);
  }
}

Liveness mówi, czy proces żyje, readiness - czy może przyjmować ruch, a startup - czy aplikacja poprawnie wstała. TerminusModule.forRoot({ gracefulShutdownTimeoutMs: 10000 }) domyka zero-downtime: po SIGTERM readiness zwraca 503 ze statusem shutting_down, a aplikacja jeszcze przez 10 sekund obsługuje ruch. W teście zwykłe endpointy odpowiadały w tym czasie 200, więc Kubernetes zdąży zabrać pod z puli.

Migracje bazy danych - zero-downtime

Migracje to najtrudniejszy element zero-downtime deployment, bo stary i nowy kod współistnieją z tą samą bazą. Zasada: migracja musi być kompatybilna wstecz. ALTER TABLE legions RENAME COLUMN name TO legion_name powoduje downtime, bo stary kod szuka name i pada. Bezpieczna zmiana nazwy pola to trzy wdrożenia. Pierwsze dodaje nowe pole:

// Migracja 1 (wdrożenie 1): dodaj nowe pole legion_name
import { Db } from 'mongodb';

export async function up(db: Db) {
  await db.collection('legions').updateMany(
    {},
    [{ $set: { legion_name: '$name' } }]
  );
  // Stary kod dalej czyta 'name' - działa!
}

Aktualizacja z potokiem kopiuje wartość name do legion_name w każdym dokumencie MongoDB, a stary kod niczego nie zauważa.

Drugie wdrożenie zmienia kod:

// Kod v2 (wdrożenie 2): zapisuj do obu pól
async updateLegion(id: string, name: string) {
  await this.model.updateOne(
    { _id: id },
    { $set: { name, legion_name: name } }
  );
}

// Czytaj z nowego pola
async getLegion(id: string) {
  const doc = await this.model.findById(id);
  return doc?.legion_name ?? doc?.name; // Fallback
}

Kod v2 pisze do obu pól i czyta nowe, z powrotem do starego dla dokumentów, których migracja nie objęła.

Trzecie sprząta:

// Migracja 3 (po pełnym wdrożeniu v2): usuń stare pole
import { Db } from 'mongodb';

export async function up(db: Db) {
  // Najpierw uzupełnij dokumenty zapisane przez stary kod w trakcie wdrożenia
  await db.collection('legions').updateMany(
    { legion_name: { $exists: false } },
    [{ $set: { legion_name: '$name' } }]
  );

  await db.collection('legions').updateMany(
    {},
    { $unset: { name: '' } }
  );
}

Najpierw uzupełniamy dokumenty zapisane przez stary kod już po pierwszej migracji. Pierwsza wersja od razu usuwała name i w teście dokument dodany w trakcie wdrożenia stracił nazwę.

Feature Flags

Feature flagi to tajne rozkazy cesarza - włączają i wyłączają funkcje bez wdrażania nowego kodu:

// src/features/feature-flag.service.ts
import { Injectable } from '@nestjs/common';

interface FeatureFlag {
  name: string;
  enabled: boolean;
  rolloutPercentage: number; // 0-100
  allowedUsers: string[];
}

@Injectable()
export class FeatureFlagService {
  private flags: Map<string, FeatureFlag> = new Map();

  setFlag(flag: FeatureFlag) {
    this.flags.set(flag.name, flag);
  }

  isEnabled(flagName: string, userId?: string): boolean {
    const flag = this.flags.get(flagName);
    if (!flag) return false;

    // Flaga całkowicie wyłączona
    if (!flag.enabled) return false;

    // Użytkownik na liście dozwolonych (np. testerzy)
    if (userId && flag.allowedUsers.includes(userId)) {
      return true;
    }

    // Stopniowe wdrażanie (procentowy rollout)
    if (flag.rolloutPercentage < 100) {
      // Nazwa flagi w hashu - każda flaga losuje innych użytkowników
      const hash = this.hashUserId(`${flagName}:${userId || 'anonymous'}`);
      return (hash % 100) < flag.rolloutPercentage;
    }

    return true;
  }

  private hashUserId(userId: string): number {
    let hash = 0;
    for (let i = 0; i < userId.length; i++) {
      hash = ((hash << 5) - hash) + userId.charCodeAt(i);
      hash |= 0;
    }
    return Math.abs(hash);
  }
}

setFlag() dodałem, bo wcześniej mapy nic nie wypełniało. Nazwa flagi w hashu sprawia, że każda flaga wybiera innych użytkowników: bez niej w teście ci sami 20% użytkowników trafiało do każdego rolloutu. W produkcji flagi trzyma się w bazie albo w usłudze, np. Unleash.

Kontroler pyta serwis przy każdym żądaniu:

// Użycie w kontrolerze
@Controller('legions')
class LegionsController {
  constructor(private features: FeatureFlagService) {}

  @Get()
  async getLegions(@Req() req) {
    if (this.features.isEnabled('new-ranking-system', req.user?.id)) {
      return this.getNewRanking();
    }
    return this.getOldRanking();
  }
}

Metody rankingów pominąłem, a req.user ustawia strażnik JWT.

PM2 Cluster Mode

PM2 w trybie cluster to jak rozmieszczenie wielu garnizonów - wykorzystuje wszystkie rdzenie CPU, restartuje procesy i przeładowuje je bez przestoju:

// ecosystem.config.cjs - konfiguracja PM2 (.cjs, bo projekt NestJS 12 to moduł ES)
module.exports = {
  apps: [{
    name: 'imperium-api',
    script: 'dist/main.js',
    instances: 'max',       // Użyj wszystkich rdzeni CPU
    exec_mode: 'cluster',   // Tryb klastrowy
    autorestart: true,
    watch: false,
    max_memory_restart: '500M',

    // Zero-downtime reload
    wait_ready: true,        // Czekaj na process.send('ready')
    listen_timeout: 10000,   // Max czas na gotowość
    kill_timeout: 5000,      // Czas na graceful shutdown

    env_production: {
      NODE_ENV: 'production',
      PORT: 3000,
    },
  }],
};

Plik ma rozszerzenie .cjs, bo module.exports nie zadziała w projekcie z "type": "module". wait_ready każe czekać na sygnał gotowości (domyślnie 3 s, tu listen_timeout 10 s), a kill_timeout zastępuje domyślne 1,6 s na zamknięcie.

Sygnał gotowości wysyła main.ts:

// W main.ts - sygnalizacja gotowości
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableShutdownHooks(); // PM2 zatrzymuje proces sygnałem SIGINT
  await app.listen(3000);

  // Powiadom PM2 że aplikacja jest gotowa
  if (process.send) {
    process.send('ready');
  }
}

PM2 zatrzymuje procesy sygnałem SIGINT, który enableShutdownHooks() zamienia w porządny odwrót. process.send istnieje tylko wtedy, gdy proces ma kanał IPC do PM2.

Komendy PM2 dla zero-downtime:

# Start z pliku konfiguracyjnego (.cjs trzeba podać wprost)
pm2 start ecosystem.config.cjs --env production

# Reload bez downtime (graceful)
pm2 reload imperium-api

# Status instancji
pm2 status

# Monitorowanie w czasie rzeczywistym
pm2 monit

pm2 reload w trybie cluster restartuje procesy po kolei, więc zawsze któryś obsługuje ruch.

Blue-green, rolling updates i feature flagi to potężne narzędzia w arsenale każdego architekta Imperium. Polecam Ci zaczynać od rolling update z dobrymi sondami, a blue-green zostawić dla systemów, w których rollback musi być natychmiastowy.

Pamiętaj: wartę zmienia się tak, żeby mur ani przez chwilę nie stał pusty.

Kod do tej lekcji: src/blue-green-deployment.ts
// Blue-Green Deployment i Zero-Downtime
// Strategie wdrazania bez przestojow

// 1. Konfiguracja Blue-Green
interface DeploymentSlot {
  name: 'blue' | 'green';
  port: number;
  version: string;
  status: 'active' | 'standby' | 'deploying';
}

const slots: Record<string, DeploymentSlot> = {
  blue: {
    name: 'blue',
    port: 3001,
    version: '2.3.0',
    status: 'active',
  },
  green: {
    name: 'green',
    port: 3002,
    version: '2.4.0',
    status: 'standby',
  },
};

// 2. Health Check Controller
// @Controller('health')
// class HealthController {
//   @Get('live')
//   liveness() { return { status: 'ok' }; }
//
//   @Get('ready')
//   readiness() {
//     // TODO: Sprawdz MongoDB, pamiec, dysk
//   }
// }

// 3. Feature Flag Service
class FeatureFlagService {
  private flags = new Map<string, { enabled: boolean; rollout: number }>();

  isEnabled(flag: string, userId?: string): boolean {
    const f = this.flags.get(flag);
    if (!f || !f.enabled) return false;
    if (f.rollout < 100 && userId) {
      // TODO: Implementuj canary release
      // Uzyj hash userId % 100 < rollout
    }
    return true;
  }
}

// 4. PM2 Cluster Config
// ecosystem.config.js:
// {
//   name: 'imperium-api',
//   script: 'dist/main.js',
//   instances: 'max',
//   exec_mode: 'cluster',
//   wait_ready: true,
//   listen_timeout: 10000,
// }

// TODO: Zaimplementuj pelny serwis rolling update
// TODO: Dodaj strategie migracji bazy danych (3 kroki)
// TODO: Skonfiguruj PM2 z graceful shutdown

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Blue-Green Deployment polega na:

Zadania praktyczne w grze

  • Edytor kodu

    Stwórz FeatureFlagService z metodą isEnabled obsługującą rolloutPercentage oraz interfejs DeploymentSlot dla blue-green

  • Układanie w pionie

    Uporządkuj kroki rolling update dla pojedynczej instancji:

  • Edytor kodu

    Stwórz plik .github/workflows/deploy.yml z jobami: test, build, deploy uruchamianymi na push do main

  • Klikanie w kolejności

    Ułóż poprawną kolejność kroków w kompletnym CI/CD pipeline:

  • Układanie w pionie

    Ułóż poprawny dekorator health check w kontrolerze NestJS:

  • Edytor kodu

    Stwórz konfigurację z Joi schema walidującą DATABASE_URL, PORT, NODE_ENV i JWT_SECRET

  • Klikanie w kolejności

    Ułóż middleware bezpieczeństwa w zalecanej kolejności dodawania do main.ts:

  1. PytanieKoncepcja Blue-Green Deployment
  2. Zadanie z kodemPraktyka: Blue-Green i Feature Flags
  3. Ułóż w kolejnościEtapy rolling update
  4. Zadanie z kodemPraktyka: Kompletny deployment pipeline
  5. Kliknij w kolejnościKroki deployment pipeline
  6. Ułóż w kolejnościHealth check w konfiguracji produkcyjnej
  7. Zadanie z kodemPraktyka: Environment validation
  8. Kliknij w kolejnościKolejność hardening middleware NestJS
  9. Projekt do wysłaniaProjekt: Infrastruktura produkcyjna Imperium
  10. WideoPodsumowanie modułu

Przydatne artykuły