Recuperação após uma falha na atualização do NGINX Plus: 'módulo "M" na versão X em vez de Y'

Liam CrillyDiretor Sênior de Gestão de Produtos

Se você estiver usando módulos dinâmicos, poderá encontrar um erro como este durante a atualização para uma nova versão do NGINX ou NGINX Plus:

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.

O motivo mais provável é que você não tenha atualizado o módulo dinâmico especificado (.so arquivo):

• Se você estiver executando o NGINX Open Source, os módulos dinâmicos deverão ser compilados para a versão para a qual você está fazendo a atualização.
• Se você estiver executando o NGINX Plus, os módulos dinâmicos deverão ser compilados com base na versão do NGINX Open Source correspondente à versão do NGINX Plus para a qual você está fazendo upgrade.

Para simplificar, daqui em diante nos referiremos apenas ao NGINX Plus.

Não entre em pânico!

Fique tranquilo: essa mensagem de erro não indica que o servidor NGINX Plus está fora do ar. As atualizações do NGINX Plus ocorrem sem interrupções; portanto, a versão antiga continua em execução quando uma atualização falha. No entanto, a atualização está incompleta e o sistema se encontra em um estado inconsistente:

• Os processos do NGINX Plus na memória estão executando a versão antiga
• Todos os arquivos em disco relacionados ao NGINX Plus correspondem à nova versão
• O módulo dinâmico mencionado na mensagem de erro foi compilado para a versão antiga

Não reinicie manualmente o nginx nem reinicialize o sistema. Isso causará indisponibilidade, pois os novos processos do NGINX Plus não poderão ser iniciados enquanto houver módulos dinâmicos incompatíveis com a nova versão do NGINX Plus.

Observe que a mensagem de erro se refere apenas ao primeiro módulo incompatível encontrado durante o processo de atualização. Portanto, é importante localizar todas as diretivas load_module na sua configuração e garantir que cada módulo seja compilado para a versão apropriada do NGINX. As versões corretas de todos os módulos dinâmicos desenvolvidos pelo NGINX e de terceiros certificados são fornecidas para cada versão do NGINX Plus<, portanto, você só precisa recompilar os módulos não certificados.Este artigo descreve como concluir o processo de atualização com segurança.

O que deu errado?

O NGINX 1.11.5 e o NGINX Plus R11 introduziram a capacidade de compilar módulos dinâmicos com base no NGINX Open Source e carregá-los no NGINX Plus. Essa compatibilidade binária exige que o módulo e o NGINX Plus compartilhem a mesma versão de código aberto de base. A atualização do NGINX Plus sem antes instalar módulos dinâmicos compilados com base na versão correspondente do NGINX Open Source falha devido a essa incompatibilidade de versões.

Se o seu módulo dinâmico foi fornecido por um fornecedor terceirizado, entre em contato com ele para obter uma nova versão compatível com a versão do NGINX correspondente à versão do NGINX Plus para a qual você pretende atualizar. Se o seu módulo dinâmico foi compilado a partir do código-fonte (e você tem acesso a ele), continue lendo.

O caminho para a recuperação

Etapa 0: Prepare o ambiente de compilação

É altamente recomendável compilar os módulos dinâmicos em um sistema separado, que chamamos aqui de “ambiente de compilação”. Isso minimiza o risco e a complexidade do sistema no qual você executa o NGINX Plus com o módulo dinâmico (chamamos esse sistema de “ambiente de produção”). O ambiente de compilação deve ter o mesmo sistema operacional e a mesma versão que o ambiente de produção; além disso, os seguintes componentes devem estar instalados:

• Utilitário UnZip
• Compilador e utilitário make
• Biblioteca de expressões regulares compatíveis com Perl (arquivos de desenvolvimento)
• Bibliotecas de compactação Zlib (arquivos de desenvolvimento)

Para garantir que esses pré-requisitos estejam instalados no seu ambiente de compilação, execute o comando a seguir.

• Para Ubuntu/Debian:

buildenv$ sudo apt-get install unzip gcc make libpcre3-dev zlib1g-dev

• Para CentOS/RHEL/Oracle Linux:

buildenv$ sudo yum install unzip gcc make pcre-devel zlib-devel

Etapa 1: Obtenha o NGINX Open Source

1. No ambiente de produção, execute o comando a seguir para identificar a versão do NGINX Open Source correspondente à versão do NGINX Plus em execução. Ela está destacada em laranja nesta saída: NGINX 1.11.10, que corresponde ao NGINX Plus R12.

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

1. No ambiente de compilação, baixe o código-fonte da versão apropriada do NGINX Open Source.

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

Etapa 2: Obtenha o código-fonte do módulo dinâmico

Copie o código-fonte do módulo dinâmico para o diretório de compilação de sua preferência. Aqui, copiamos um módulo de exemplo “hello world” do NGINX de seu repositório no GitHub.

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

Etapa 3: Compile o módulo dinâmico

1. Compile o módulo dinâmico executando primeiro o script configure do NGINX com o argumento --with-compat para tornar o módulo dinâmico compatível em nível binário com o NGINX Plus. Em seguida, execute make modules para compilar apenas o módulo.

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

1. Verifique se o processo de compilação criou o módulo dinâmico como um arquivo .so no subdiretório objs.

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

1. Crie uma cópia do arquivo do módulo com a versão do NGINX Open Source no nome do arquivo. Isso facilita o gerenciamento de várias versões do módulo dinâmico no ambiente de produção.

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

Etapa 4: Copie o módulo dinâmico para o ambiente de produção

Como criamos o módulo dinâmico com a versão do NGINX Open Source no nome do arquivo, podemos copiá-lo com segurança para o ambiente de produção sem afetar a operação.

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

Etapa 5: Substitua o módulo dinâmico

No ambiente de produção, substitua o arquivo atual pelo novo arquivo .so. É seguro fazer isso neste momento, pois os módulos dinâmicos só são carregados na memória quando o nginx é reiniciado ou quando a configuração é recarregada.

production$ cd /etc/nginx/modulesproduction$ 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

Etapa 6: conclua a atualização do NGINX Plus

1. Execute o comando a seguir para verificar se a versão do módulo está correta e se o NGINX Plus está pronto para concluir o processo de atualização.

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

1. Conclua o processo de atualização para que o NGINX Plus use a nova versão e os módulos dinâmicos.

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

Evitando a falha na atualização

Na próxima vez que você atualizar o NGINX Plus, poderá economizar tempo e evitar erros seguindo estas instruções antes da atualização, para que os módulos dinâmicos atualizados já estejam disponíveis quando você iniciar o processo de atualização.

Sobre o autor

Liam CrillyDiretor Sênior de Gestão de Produtos

Mais publicações de Liam Crilly