NGINX 업그레이드 실패에서 복구

동적 모듈을 사용하는 경우 새 NGINX 업그레이드 하는 동안 다음과 같은 오류가 표시될 수 있습니다. 이 포스트에서는 모듈 “M”버전 Y 대신 X를 이용하여 해결하는 방법을 알아보겠습니다.

Setting up nginx-plus (1.11.10-1~xenial) ...

nginx: [emerg] module "/etc/nginx/modules/ngx_http_geoip_module.so" version 1011005 instead of 1011006 in /etc/nginx/nginx.conf:7

nginx: configuration file /etc/nginx/nginx.conf test failed

invoke-rc.d: initscript nginx, action "upgrade" failed.

가장 가능성이 높은 이유는 지정된 동적 모듈(.so 파일)을 업그레이드 하지 않았기 때문입니다.

  • NGINX Open Souce를 실행 중인 경우 업그레이드하려는 버전에 대해 동적 모듈을 컴파일해야 합니다.
  • NGINX Plus를 실행 중인 경우 업그레이드하려는 NGINX Plus 릴리스에 해당하는 NGINX Open Souce 버전에 대해 동적 모듈을 컴파일해야 합니다.

이 포스트에서는 NGINX Plus로 진행하겠습니다.

목차

1. 당황하지 말 것
2. NGINX 업그레이드 무엇이 잘못되었나요?
3. NGINX 업그레이드 실패 복구하는 방법
0단계: 빌드 환경 준비
1단계: NGINX Open Souce 얻기
2단계: 동적 모듈 소스 얻기
3단계: 동적 모듈 컴파일
4단계: 프로덕션 환경에 동적 모듈 복사
5단계: 동적 모듈 교체
6단계: NGINX Plus 업그레이드 완료
4. NGINX 업그레이드 실패 방지

1. 당황하지 말 것

이 오류 메시지는 NGINX Plus 서버가 다운되었음을 나타내지 않으므로 안심하십시오. NGINX Plus 업그레이드 는 원활하므로 업그레이드가 실패해도 이전 버전이 계속 실행됩니다. 그러나 업그레이드가 완료되지 않고 기존 상태에서 진행됩니다.

  • 메모리의 NGINX Plus 프로세스가 이전 버전을 실행 중입니다.
  • NGINX Plus와 관련된 디스크의 모든 파일은 새 버전에 해당합니다.
  • 오류 메시지에 언급된 동적 모듈은 이전 버전에 대해 컴파일됩니다.

NGINX를 수동으로 다시 시작하거나 시스템을 재부팅하지 마십시오. 그렇게 하면 새로운 NGINX Plus 릴리스와 동기화되지 않은 동적 모듈이 있는 동안에는 새로운 NGINX Plus 프로세스를 시작할 수 없기 때문에 다운타임이 발생합니다.

오류 메시지는 업그레이드 프로세스 중에 발견된 첫 번째 호환되지 않는 모듈에만 관련되므로 구성에서 모든 load_module 지시문을 찾고 모든 모듈이 적절한 NGINX 버전에 대해 컴파일되었는지 확인하는 것이 중요합니다. NGINX가 작성하고 인증한 모든 third-party dynamic module의 올바른 버전이 각 NGINX Plus 릴리스에 제공되므로 인증되지 않은 모듈만 다시 컴파일해야 합니다. 이 포스트에서는 업그레이드 프로세스를 안전하게 완료하는 방법을 설명합니다.

2. NGINX 업그레이드 무엇이 잘못되었나요?

NGINX 1.11.5 및 NGINX Plus R11에는 NGINX Open Souce에 대해 동적 모듈을 컴파일하고 NGINX Plus에 로드하는 기능이 도입되었습니다. 이 바이너리 호환성은 모듈과 NGINX Plus가 동일한 기본 오픈 소스 버전을 공유해야 합니. 해당 NGINX Open Souce 버전에 대해 빌드된 동적 모듈을 먼저 설치하지 않고 NGINX Plus를 업그레이드 하면 이 버전 불일치로 인해 실패합니다.

third‑party 공급업체에서 동적 모듈을 제공한 경우 업그레이드 하려는 NGINX Plus 릴리스의 NGINX 버전과 일치하는 새 버전에 대해 공급업체에 문의해야 합니다.

3. NGINX 업그레이드 실패 복구하는 방법

복구하는 방법은 다음과 같습니다.

0단계: 빌드 환경 준비

여기서는 “빌드 환경”이라고 하는 별도의 시스템에서 동적 모듈을 컴파일하는 것이 좋습니다. 이렇게 하면 동적 모듈과 함께 NGINX Plus를 실행하는 시스템의 위험과 복잡성을 최소화할 수 있습니다(이를 “프로덕 환경”이라고 함). 빌드 환경은 운영체제 및 버전이 프로덕션 환경과 동일해야 합니다. 또한 다음 구성 요소를 설치해야 합니다.

  • 압축 해제 유틸리티
  • 컴파일러 및 make 유틸리티
  • Perl 호환 정규 표현식 라이브러리(개발 파일)
  • Zlib 압축 라이브러리(개발 파일)

빌드 환경에 이러한 전제 조건이 설치되어 있는지 확인하려면 다음 명령을 실행하십시오.

  • Ubuntu 및 Debian:
buildenv$ sudo apt-get install unzip gcc make libpcre3-dev zlib1g-dev
  • CentOS / RHEL / Oracle Linux:
buildenv$ sudo yum install unzip gcc make pcre-devel zlib-devel

1단계: NGINX Open Souce 얻기

1. 프로덕션 환경에서 작업하면서 다음 명령을 실행하여 실행 중인 NGINX Plus 릴리스에 해당하는 NGINX Open Souce 버전을 식별합니다. 버전은 주황색으로 강조 표시되어 있습니다: NGINX Plus R12에 해당하는 NGINX 1.11.10.

production$ nginx -v
nginx version: nginx/1.11.10 (nginx-plus-r12)

2. 빌드 환경에서 작업하면서 적절한 NGINX Open Souce 버전의 소스를 다운로드합니다.

build-env$ wget -qO - http://nginx.org/download/nginx-1.11.10.tar.gz | tar zxfv -

2단계: 동적 모듈 소스 얻기

동적 모듈의 소스 코드를 선택한 빌드 디렉터리에 복사합니다. 여기서는 GitHub 리포지토리에서 샘플 NGINX “hello world” 모듈을 복사합니다.

buildenv$ git clone https://github.com/perusio/nginx-hello-world-module.git
Cloning into 'nginx-hello-world-module'...

3단계: 동적 모듈 컴파일

1. –with-compat 인수와 함께 NGINX 구성 스크립트를 먼저 실행하여 동적 모듈을 NGINX Plus와 바이너리 호환되도록 만들어 동적 모듈을 컴파일합니다. 그런 다음 make module을 실행하여 모듈만 컴파일합니다.

buildenv$ cd nginx-1.11.10/
buildenv$ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module
buildenv$ make modules

2. 빌드 프로세스가 objs 하위 디렉터리에 .so 파일로 동적 모듈을 생성했는지 확인합니다.

buildenv$ ls objs/*.so
objs/ngx_http_hello_world.so

3. 파일 이름에 NGINX Open Souce 버전이 포함된 모듈 파일의 복사본을 만듭니다. 이렇게 하면 프로덕션 환경에서 여러 버전의 동적 모듈을 더 간단하게 관리할 수 있습니다.

buildenv$ cp objs/ngx_http_hello_world.so ./ngx_http_hello_world_1.11.10.so

4단계: 프로덕션 환경에 동적 모듈 복사

파일 이름에 NGINX Open Souce 버전을 포함하여 동적 모듈을 생성했기 때문에 운영에 영향을 주지 않고 프로덕션 환경에 안전하게 복사할 수 있습니다.

buildenv$ scp ./ngx_http_hello_world_1.11.10.so production:/etc/nginx/modules

5단계: 동적 모듈 교체

프로덕션 환경에서 작업하면서 새 .so 파일을 교체하여 현재 파일을 바꿉니다. 동적 모듈은 NGINX가 다시 시작되거나 구성이 다시 로드될 때만 메모리에 로드되기 때문에 이 시점에서 수행하는 것이 안전합니다.

production$ cd /etc/nginx/modules
production$ cp ngx_http_hello_world.so ngx_http_hello_world_ROLLBACK.so
production$ ln -fs ngx_http_hello_world_1.11.10.so ngx_http_hello_world.so
production$ ls -gG
-rw-r--r-- 1 243576 Jan 31 16:18 ngx_http_hello_world_1.11.10.so
-rw-r--r-- 1 243576 Oct 20 10:40 ngx_http_hello_world_ROLLBACK.so
lrwxrwxrwx 1     24 Jan 31 16:26 ngx_http_hello_world.so -> ngx_http_hello_world_1.11.10.so

6단계: NGINX Plus 업그레이드 완료

1. 다음 명령을 실행하여 모듈 버전이 올바른지, NGINX Plus가 업그레이드 프로세스를 완료할 준비가 되었는지 테스트합니다.

production$ nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

2. NGINX Plus가 새 릴리스 및 동적 모듈을 사용하도록 업그레이드 프로세스를 완료하십시오.

production$ service nginx upgrade
Starting new master nginx:                                 [  OK  ]
Graceful shutdown of old nginx:                            [  OK  ]

4. NGINX 업그레이드 실패 방지

다음에 NGINX Plus를 업그레이드 할 때 업그레이드 프로세스를 시작할 때 업데이트된 동적 모듈을 이미 사용할 수 있도록 업그레이드 전에 다음 지침을 따르면 시간을 절약하고 오류를 방지할 수 있습니다.

NGINX Plus를 사용해 보려면 지금 무료 30일 평가판을 시작하거나 당사에 연락하여 사용 사례에 대해 문의하십시오.

또한 NGINX에 대한 최신 소식을 빠르게 전달받고 싶으시면 아래 뉴스레터를 구독하세요.