Paulo Benjamin

Posted on Nov 4, 2024

Upgrade do MongoDB - o guia definitivo.

Uma das maiores dúvidas [e medos] dos desenvolvedores, e dos DBAs relacionais que herdam a administração de servidores MongoDB, é o upgrade de versão do binário - afinal, em time que ganha não se mexe, certo? ERRADO! Manter os binários atualizados, é uma das principais recomendações da fabricante.

Então, segue aqui um passo a passo que vai ajudar você a realizar o upgrade do MongoDB na maioria dos ambientes e cenários sem dor de cabeça. Claro, é impossível prever todos os possíveis cenários de implementação de MongoDB - por exemplo, não estou abordando nada envolvendo kubernetes aqui - mas fiz meu melhor para ajudar o maior número de pessoas possíveis.

PS.: Originalmente eu deveria lançar dois artigos esta semana, já que não consegui lançar o da última semana a tempo, visto que minha programação é lançar um artigo por semana. Mas com a correria do MongoDB .Local de São Paulo, no último 30 de Outubro, não consegui lançar o artigo da semana passada, e vou lançar dois esta semana. Como havia prometido ha um amigo no .Local este artigo para hoje, inverti a ordem dos artigos, para cumprir com minha palavra. Espero que seja de ajuda!

Considerações iniciais:

É importante verificar se os diretórios onde estão os arquivos de dados, o keyfile e verificar se o .pid foi apagado.

No Ubuntu o nome do usuário de serviço do MongoDB é mongodb enquanto que na maioria das outras distros é mongod.

Arquivos de dados - pode ser obtido no arquivo de configuração */etc/mongod.conf*:
- chown -R mongod:mongod
- chmod -R 744
Keyfile - pode ser obtido no arquivo de configuração /etc/mongod.conf:
- chown mongod:mongod
- chmod 400
.PID - este último varia muito de acordo com a distro:
- rm -F /var/run/mongod/*.pid

Tendo estas informações em vista, segue o padrão para upgrade de versão do MongoDB:

Upgrade

O upgrade do MongoDB, quando em replica set ou shard deve começar com os nós secundários. Nos shard ele o ideal é fazer um shard por vez. O último nó a ser atualizado é o primário.

A atualização sempre deve ocorrer de versão em versão, ou seja, um MongoDB 4.4 não pode ir direto para a 8.0. Ele deve seguir o caminho 4.4 → ****5.0 → 6.0 → 7.0 → 8.0.

O processo consiste em atualizar o arquivo de repositório, realizar o shutdown do MongoDB por dentro dele, verificar se ele realmente não está mais em execução, rodar o comando de upgrade, iniciar o serviço do MongoDB, e atualizar o compatibility version do MongoDB para a nova versão. Abaixo segue um script de upgrade de versão para CentOS 9.

Passo 1: Silent Shutdown

Para garantir que não haverá corrupção ou perda de dados é importante fazer o shutdown do Mongo corretamente, isto é, por dentro dele.

Para isso precisamos logar no Mongo, localmente, com um usuário com permissão root e executar o db.shutdownServer(), executando linha a linha do código que segue:

# mongo admin --host localhost --port <27017> --username <admin> --password <admin>
...
rs01 [secondary] admin> db.shutdownServer()
rs01 [secondary] admin> exit

Passo 2: Verificação do shutdown

Em seguida é bom verificar se o serviço realmente está parado. No CentOS pode ser feito executando a primeira linha do código abaixo. A saída esperada são as linhas que seguintes.

# systemctl status mongod
● mongod.service - MongoDB Database Server
   Loaded: loaded (/usr/lib/systemd/system/mongod.service; enabled; vendor preset: disabled)
   Active: inactive (**dead**) since Sun 2024-03-24 04:23:19 UTC; 8s ago
     Docs: https://docs.mongodb.org/manual
  Process: 32831 ExecStart=/usr/bin/mongod $OPTIONS (code=exited, status=0/SUCCESS)
 Main PID: 32831 (code=exited, status=0/SUCCESS)

Mar 24 03:47:10 ip-172-31-38-118.sa-east-1.compute.internal systemd[1]: Started MongoDB Database Server.
Mar 24 03:47:10 ip-172-31-38-118.sa-east-1.compute.internal mongod[32831]: {"t":{"$date":"2024-03-24T03:47:10.931Z"},"s>
Mar 24 04:23:19 ip-172-31-38-118.sa-east-1.compute.internal systemd[1]: mongod.service: Succeeded.

Passo 3: Atualização do repositório

Nesse passo alteramos o repositório para o repositório da nova versão. Em distros RHEL o repositório fica em “/etc/yum.repos.d/”. O nome do arquivo sempre começa com “mongodb” e termina com “.repo”.

O script abaixo já faz a substituição do conteúdo do arquivo do repositório ao ser executado. No caso deste código, o nome do arquivo de repositório, que está no fim da primeira linha é mongodb.repo.

O repositório é para Linux REHL 8 (em laranja a seguir) e para a versão 8.0 do MongoDB (em azul) como mostra a 4ª linha do código: “baseurl=https://repo.mongodb.org/yum/**redhat/8**/**mongodb-org/8.0**/x86_64/”.

Na penúltima linha também há citação da versão do MongoDB, que deve ser alterada junto com as outras informações caso o upgrade não seja para as mesmas versões, seja de Linux, seja de Mongo.

No fim deste passo a passo vou juntar algumas partes que podem ser executadas em conjunto.

#  cat << 'ENDOFDOC' | sudo tee /etc/yum.repos.d/mongodb.repo 
[mongodb-org]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/8/mongodb-org/8.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://pgp.mongodb.com/server-8.0.asc
ENDOFDOC

Passo 4: Atualizar o binário

Aqui fazemos diretamente a atualização do binário do MongoDB. Por segurança é bom realizar um backup do arquivo de configuração do Mongo. Para isso, podemos executar os comando a seguir no Shell.

# sudo cp /etc/mongod.conf /etc/mongodconf.upgradeBkp
# sudo yum upgrade mongodb-org -y

Para algumas versões do Mongo essa instrução pode falhar. Isso por que o nome do pacote muda em algumas versões. Você pode tentar as seguinte variações para o nome do pacote:

mongodb
mongodb-org
mongodb-*
mongodb*

Passo 5: Iniciar o Mongo com o novo binário

Para iniciar o MongoDB com o novo binário usamos o systemctl start mongod. E em seguida é importante utilizar o comando systemctl status mongod para verificar se o serviço foi iniciado sem nenhum problema. Se tudo estiver ok, o resultado será como o mostrado a seguir:

# systemctl start mongod
# systemctl status mongod
● mongod.service - MongoDB Database Server
   Loaded: loaded (/usr/lib/systemd/system/mongod.service; enabled; vendor preset: disabled)
   Active: active (**running**) since Sun 2024-03-24 04:40:06 UTC; 24s ago
     Docs: https://docs.mongodb.org/manual
 Main PID: 59443 (mongod)
   Memory: 170.8M
   CGroup: /system.slice/mongod.service
           └─59443 /usr/bin/mongod -f /etc/mongod.conf

Mar 24 04:40:06 ip-172-31-38-118.sa-east-1.compute.internal systemd[1]: **Started** MongoDB Database Server.

No caso de haver algum erro seguem alguns passos importantes a verificar já citados no início do arquivo:

Verificar permissão de diretórios e arquivos

Todos os diretórios e arquivos citados no arquivo de configuração do MongoDB, exceto o de time zone, precisam ter como dono o usuário de serviço do MongoDB: mongod. Por isso podemos iniciar verificando todos os paths citados lá, no arquivo /etc/mongod.conf.

Em geral teremos os seguinte paths:

systemLog: /var/log/mongodb/mongod.log
storage: /var/lib/mongo
security.keyFile: /etc/mongodb.key

Os arquivos e diretório acima são os padrão. É importante lembrar que cada instalação pode ter estes arquivos em outros caminhos. Pensando nos caminhos padrão, a correção para os problemas de permissão seria executar o seguinte script:

# chmod -R mongod:mongod /var/log/mongodb/mongod.log
# chown -R 744 /var/log/mongodb/mongod.log
# chmod -R mongod:mongod /var/lib/mongo
# chown -R 744 /var/lib/mongo
# chmod mongod:mongod /etc/mongodb.key
# chown 400 /etc/mongodb.key

Observe que a permissão do keyFile é bem restritiva, permitindo leitura somente ao usuário mongod, e nada mais.

Passo 6: Atualizar a primária

Após concluir a atualização de todos os nós secundários, vamos partir para atualizar o nó primário. O processo em si é basicamente o mesmo, mas há uma pequena diferença no silent shutdown: antes de executar o db.shutdownServer(), devemos forçar uma troca de nó primário com o comando stepdown, como mostra a seguir:

# mongo admin --host localhost --port <27017> --username <admin> --password <admin>
...
rs01 [primary] admin> rs.stepDown()
rs01 [secondary] admin> db.shutdownServer()
rs01 [primary] admin> exit

Após a execução deste passo, você pode seguir dos passos 2 a 5.

Passo 7: Atualizar o Compatibility Version do replica set

Se você chegou aqui, é por que você terminou a atualização com sucesso. No entanto, o MongoDB continua funcionando com a versão anterior, por que ele tem algo chamado compatibility version, o que permite que atualizemos um nó para uma versão superior a dos demais sem que ele pare de funcionar ou apresente conflitos.

Essa configuração também é a que permite fazer um downgrade de forma tranquila para a maioria das versões. De forma que, para finalizar esta atualização precisamos atualizar o compatibility version, o que fazemos com o código a seguir no nó primário:

# mongo admin --host localhost --port <27017> --username <admin> --password <admin>
...
rs01 [primary] admin> db.adminCommand({setFeatureCompatibilityVersion: "8.0", 
                                      confirm: true})

Para confirmar se realmente estamos com o compatibility version correto, podemos executar o seguinte comando na mesma sessão do Mongo, recebendo o resultado:

rs01 [primary] admin> db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1})
{
  ***featureCompatibilityVersion: { version: '8.0' }*,**
  ok: 1,
  '$clusterTime': {
    clusterTime: Timestamp({ t: 1660318752, i: 5 }),
    signature: {
      hash: Binary(Buffer.from("ce0cff3621e9b089fa6d8e9a1e1efc1a1ff15dab", "hex"), 0),
      keyId: Long("7129893797260951557")
    }
  },
  operationTime: Timestamp({ t: 1660318752, i: 5 })
}

Códigos agrupados:

Atualização de repositório, upgrade do binário e restart do serviço.

Após realizar o Silent Shutdown do nó, podemos executar o código abaixo que realizará a alteração do repositório, o backup do arquivo de configuração, e o upgrade do binário, bem como o restart do serviço do MongoDB.


cat << 'ENDOFDOC' | sudo tee /etc/yum.repos.d/mongodb.repo 
[mongodb-org]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/8/mongodb-org/8.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://pgp.mongodb.com/server-8.0.asc
ENDOFDOC

sudo cp /etc/mongod.conf /etc/mongodconf.upgradeBkp
sudo yum upgrade mongodb-org -y
systemctl start mongod
systemctl status mongod

Correção das permissões dos diretórios e arquivos

No caso de ocorrer algum erro no restart do serviço é importante verificar a permissão dos arquivos. O código abaixo é um exemplo de correção das permissões. Mas é sempre importante lembrar que os caminhos podem variar de instalação para instalação. Os caminhos que estão no script são os caminhos padrão para o CentOS. No entanto, por exemplo, nas instalações que eu faço, eu costumo mudar o diretório de log e de dados bem como o keyfile para o diretório /mongo. Dentro dele eu crio subdiretórios ssh, data, log. Com isso, eu precisaria alterar os caminhos no script abaixo.

chmod -R mongod:mongod /var/log/mongodb/mongod.log
chown -R 744 /var/log/mongodb/mongod.log
chmod -R mongod:mongod /var/lib/mongo
chown -R 744 /var/lib/mongo
chmod mongod:mongod /etc/mongodb.key
chown 400 /etc/mongodb.key