Docker 컨테이너 종료 시 Nest.js가 바로 꺼지는 이유 enableShutdownHooks / SIGTERM

도커 컨테이너 안에 nest.js 어플리케이션이 동작하고 있을때 컨테이너를 멈추게되면 nest.js의 안의 프로세스는 모든 작업이 끝마쳐지지 않고 종료되는 경우가 발생합니다.

오늘은 이와 관련한 설정에 대해 알아보겠습니다.

우선, Dokcer 컨테이너 종료시에 기본적으로 10s 의 프로세스가 멈출 대기시간이 주어집니다. 
이 시간안에 프로세스가 끝나거나 하면 문제가 되지않겠지만 마냥 그렇게 일이 수월하게 풀리진 않습니다.

stop_grace_period 

해당시간보다 더 많은 시간이 필요할경우에는 도커 컴포즈의 stop_grace_period 설정을 기호에 맞게 지정해주면 됩니다.

<docke-compose file>
stop_grace_period: 30s

해당 설정의 경우에는 공식적으로 최대시간이 딱히 정해져 있지않아서 프로젝트의 설정, 환경에 맞게 지정해주시면 됩니다.

이렇게 지정하게되면 해당프로젝트의 종료시 30초의 대기 시간이 발생하게 됩니다. 

도커 컨테이너를 종료한다면 프로세스는 아래와 같이 동작하게 됩니다.

도커 종료시 프로세스 흐름

 docker stop → SIGTERM 전송 → stop_grace_period 동안 대기 → 안 끝나면 SIGKILL.

위와 같은 흐름으로써 동작 하게 되며 Docker 컨테이너의 종료를 하게되면 SIGTERM이라는 메세지를 기본값으로 각 프로세스에 전달하게 됩니다.

<docke-compose file>
stop_signal: SIGTERM

단 위의경우 아래처럼 main.ts에 아래와 같이 필요한 신호를 추가해주고 그에맞는 로직을 별도로 작성해야합니다.

//main.ts

app.enableShutdownHooks(['SIGTERM', 'SIGINT', 'SIGHUP']); // 필요 신호 추가

 

//별도 서비스.ts

  import { BeforeApplicationShutdown } from '@nestjs/common';

  export class AppService implements BeforeApplicationShutdown {

    beforeApplicationShutdown(signal?: string) {

      if (signal === 'SIGHUP') { /* SIGHUP 전용 처리 */ }

      else { /* 공통 정리 */ }

    }

  }

 

 

app.enableShutdownHooks();

위 메서드는 main.ts에 위치하여야하고 enbaleShutdownHooks의 역할은 프로세스가 멈출때의 신호를 받아서 처리하는 이벤트입니다.

즉 이벤트이니 만큼 이벤트를 받아서 전달하는 게 필요한대 이를 처리하는 인터페이스가 OnApplicationShutdown입니다.

해당인터페이스를 구현해서 아래와 같이 설정 해보겠습니다. 또 main.ts에는 shutdownHooks를 호출하겠습니다.

import { Injectable, OnApplicationShutdown } from '@nestjs/common';

@Injectable()

export class AppService implements OnApplicationShutdown {

  getHello(): string {

    return 'Hello World!!';

  }

  public async onApplicationShutdown() {

    console.log('AppService onApplicationShutdown', new Date().toISOString());

    console.log('데이터베이스 종료', new Date().toISOString());

    console.log('기타레디스 종료 ', new Date().toISOString());

  }

}

 

 

 

import { Controller, Get, Post, Body } from '@nestjs/common';

import { AppService } from './app.service';

@Controller()

export class AppController {

  constructor(private readonly appService: AppService) {}

  // @Get()

  // getHello(): string {

  //   return this.appService.getHello();

  // }

  @Get('test-long')

  async testLong() {

    console.log('=== 테스트 시작 ===', new Date().toISOString());

    // 20초 동안 작업 시뮬레이션

    for (let i = 0; i < 20; i++) {

      console.log(`작업 중... ${i + 1}/20`);

      await new Promise((resolve) => setTimeout(resolve, 1000));

    }

    console.log('=== 테스트 완료 ===', new Date().toISOString());

    return { message: '테스트 완료', timestamp: new Date().toISOString() };

  }

}

 

 

 //main.ts

  // Graceful shutdown 설정 (테스트용 주석처리 가능)

  app.enableShutdownHooks();

 

그리고 docker run을 통해서 도커를 실행해준뒤 

docker logs -f <컨테이너명> 으로 로그를 확인해주면 아래와같이 프로세스가 실행되는걸 볼수 있습니다.

여기서 프로세스가 끝날때 쯤에 아래와 같이컨테이너로 stop을 해줍니다.

docker stop <컨테이너 명>

이렇게 되면 해당 stop 명령어를 내린 시점부터 onApplicationShutdown의 메서드가 실해오디는것을 확인할 수 있습니다. 

레디스,데이터베이스 종료 로그가 찍히는 모습

즉 ApplicationShutDown시 훅이 제대로 실행되는걸 볼수 있는데 이때 도커 컨테이너의 stop시 기본 대기시간은 10s 이기에 기존의 실행중인 프로세스가 10s 이상 남은 경우 ApplicationShutDown이 제대로 실행되기 전에 도커 컨테이너가 stop될 수 있으니 앞서 말했던 stop_grace_peroid 설정을 꼭 넉넉하게 해야 합니다.

위 이미지 처럼 프로세스가 4까지만 실행된 시점 stop을 하니 10s이후인 14부터는 onApplicatonShutdown메서드가 제대로 실행되지 않고 컨테이너가 종료되어버림

 

이로써 nest.js와 컨테이너의 동작들을 이해해야 설계할때도 의도한대로 동작하니 유의해야 합니다.