Informe Técnico Nº 03, de 04 de Abril de 2024
Este informe detalha o procedimento a ser adotado para migração de peers b-Cadastros que ainda estão utilizando Sistema Operacional CentOS 7 para um dos seguintes sistemas atualmente suportados: AlmaLinux, Rocky Linux ou RedHat, todos na versão 9.3+. Essa migração é fortemente recomendada, tendo em vista que o CentOS 7 perderá suporte à partir de 30 de junho de 2024. (Centos 7 EOL)
Atenção!
É importante que seja realizada a leitura completa deste procedimento antes de realizá-lo passo a passo.
Este procedimento deve ser seguido apenas por participantes que possuam peers que ainda estejam utilizando o Sistema Operacional CentOS 7.
Qualquer dúvida deve ser encaminhada via solicitação de suporte.
O procedimento consiste basicamente em:
- Realizar o backup do peer atual, com CentOS7;
- Restaurar o peer em um servidor novo, instalado com um dos novos sistemas suportados;
- Readequar as possíveis integrações dos sistemas internos do participante com o novo peer;
- Desativar o antigo peer com CentOS7.
Para isso, devem ser utilizados os scripts de backup e restore fornecidos por esta documentação. Como este procedimento pode indisponibilizar o serviço do peer b-Cadastros por algumas horas, deve ser feito em horário reservado para manutenção. Sugerimos uma janela de 3h para a realização do procedimento completo (backup, restore e verificações).
Pré-Requisitos
- Realizar instalação de um novo servidor (físico ou virtual) utilizando um dos sistemas operacionais homologados, conforme consta na seção de pré-requisitos;
- Atender aos pré-requisitos de rede, segurança, especificações etc, para este novo servidor (atentar para regras de saída necessárias para a instalação de um novo peer);
- A Faixa de IPs de saída do novo servidor deve ser a mesma utilizada pelo anterior com CentOS 7. Caso o IP de saída utilizado pelo novo servidor seja diferente do peer com CentOS 7, é preciso solicitar ao suporte do Serpro a mudança de IP;
- Disponibilizar área de armazenamento externo (storage de rede, disco virtual, disco externo ou compartilhamento NFS) para a cópia dos dados entre os servidores antigo e novo;
- Identificar todos os sistemas que utilizam ou se integram ao atual peer do participante e planejar a reconfiguração destes para utilizarem o novo peer;
- Reservar horário de manutenção para a realização do procedimento.
Verificação prévia do peer CentOS 7
Antes de dar início aos procedimentos, verifique se o peer com CentOS 7 está funcionando normalmente com o comando:
O resultado do comando acima deve ser algo semelhante a:
IMAGE STATUS NAMES
monitoracao/appmon:latest Up 1 months ago appmon
nginx:1.22 Up 1 months ago nginx
hyperledger/fabric-peer:2.4.7 Up 1 months ago <nome_do_peer>
couchdb:3.2.2 Up 1 months ago couchdb
hyperledger/fabric-tools:2.4.7 Up 1 months ago cli
Verifique os logs do contêiner do peer com o comando:
As mensagens devem estar no padrão abaixo, indicando que o peer recebeu os últimos blocos normalmente:
...
2024-03-19 12:02:27.605 UTC [gossip.privdata] StoreBlock -> INFO 53599 Received block [332968] from buffer channel=chcpf
2024-03-19 12:02:27.615 UTC [committer.txvalidator] Validate -> INFO 5359a [chcpf] Validated block [332968] in 9ms
2024-03-19 12:02:28.788 UTC [kvledger] commit -> INFO 5359b [chcpf] Committed block [332968] with 9 transaction(s) in 1169ms (state_validation=14ms block_and_pvtdata_commit=6ms state_commit=1147ms) commitHash=[09b65fd248a86b086d98a07dd1511ab236282c5e4f3b9f459e8c5c46665efd5d]
2024-03-19 12:02:30.369 UTC [gossip.privdata] StoreBlock -> INFO 5359c Received block [332969] from buffer channel=chcpf
2024-03-19 12:02:30.383 UTC [committer.txvalidator] Validate -> INFO 5359d [chcpf] Validated block [332969] in 13ms
2024-03-19 12:02:31.695 UTC [kvledger] commit -> INFO 5359e [chcpf] Committed block [332969] with 12 transaction(s) in 1308ms (state_validation=19ms block_and_pvtdata_commit=7ms state_commit=1280ms) commitHash=[3249405423f0bef1803aa152becf34897e7ae72bebb9dc67390baad4e63da2c0]
2024-03-19 12:02:32.384 UTC [gossip.privdata] StoreBlock -> INFO 5359f Received block [332970] from buffer channel=chcpf
2024-03-19 12:02:32.401 UTC [committer.txvalidator] Validate -> INFO 535a0 [chcpf] Validated block [332970] in 16ms
2024-03-19 12:02:33.372 UTC [kvledger] commit -> INFO 535a1 [chcpf] Committed block [332970] with 8 transaction(s) in 969ms (state_validation=22ms block_and_pvtdata_commit=7ms state_commit=938ms) commitHash=[6c9ba46c9de5135cd14a495f5d60af5757e9c06b9c9a2383f9356fa193f390ac]
Verifique a página de monitoração e o status de sincronização das bases contratadas do peer, acessando o endereço:
Esta interface gráfica deverá mostrar os painéis em verde caso esteja tudo certo com o peer. Em caso de problemas, acesse o menu Ajuda, no canto superior direito da interface, para consultar o significado das indicações e acione o suporte, caso necessário.
Backup do peer atual, com CentOS7
Antes de iniciar o backup, conecte a área de armazenamento externo ao peer com CentOS 7, seja ela um storage de rede (NAS), um disco virtual (em caso de VM), um disco externo (em caso de máquina física) ou um ponto de montagem NFS. O ponto de montagem desta área será indicado como diretório de destino para o script de backup, e deve possuir capacidade de cerca de 50% do volume atualmente ocupado pelo b-Cadastros. Para verificar o volume utilizado atualmente, utilize o comando abaixo:
Esse comando irá retornar o valor em GB dos volumes utilizados por todos os contêineres da máquina. A área de armazenamento para o backup deve ter disponível pelo menos metade desse valor, em GB. Com a área de armazenamento externa montada adequadamente, seguimos com o procedimento de backup.
Atenção!
Para a realização deste procedimento, deve ser utilizado o script de backup fornecido por esta documentação.
O script de backup basicamente realiza os seguintes passos:
- Verifica se há espaço em disco suficiente no diretório de destino indicado para guarda do backup;
- Interrompe os serviços do peer b-Cadastros;
- Realiza a cópia e a compactação das seguintes pastas para o diretório de destino:
/etc/hyperledger/var/lib/docker/volumes/peer_couchdata/var/lib/docker/volumes/peer_peerdata/var/opt/bcadastros
- Faz uma cópia da imagem da aplicação de monitoração (
appmon); - Reinicia os serviços do b-Cadastros no peer;
A tarefa de compactação do passo 3 pode demorar muitas horas se for feita utilizando o compactador gzip, comum em sistemas Linux. Por isso, o script de backup foi programado para utilizar por padrão o eficiente compactador zstd, que pode reduzir em até 20 vezes o tempo de execução do procedimento de backup e restore. Para isso, antes de executar o script é necessário instalar o pacote zstd no peer com o comando: yum -y install zstd. Caso o compactador zstd não esteja instalado, o script continua o processo com o gzip, porém, o tempo de execução da compactação será consideravelmente maior.
O passo 3 pode demorar algumas horas para ser completado, a depender da quantidade e tamanho das bases contratadas e do compactador utilizado. Isso significa que os serviços do peer ficarão indisponíveis durante todo este período de tempo. Esse procedimento pode ser realizado com até um mês antes de ser feita a restauração no novo servidor, de modo que pode ser utilizada uma janela de manutenção mais curta. No entanto, deve-se considerar que quanto maior a distância entre o dia do backup e o dia do restore, mais tempo o novo peer precisará para receber todas as atualizações de base que ocorreram durante esse período, e que não constam nos arquivos do backup.
O diretório de destino dos arquivos de backup gerados pelo passo 3 deve ser passado por argumento para o script, caso contrário, será utilizado o diretório /var/bkp por padrão.
O script de backup deve ser baixado e executado da seguinte forma, no peer com CentOS 7:
sudo yum -y install zstd
# Instala o pacote zstd, requisito para uma compactação mais rápida.
curl -k -s "https://s3.i02.estaleiro.serpro.gov.br/bcad-prod-publico/backup/backup-peer.sh" -o backup-peer.sh
# Baixa o script de backup para um arquivo com nome `backup-peer.sh`
sudo bash backup-peer.sh DESTINO
# Executa o backup salvando os arquivos no diretório indicado em `DESTINO` (ex. /mnt/disco_externo)
# Caso não seja indicado o DESTINO, é utilizado o diretório `/var/bkp` por padrão
Substitua o termo DESTINO pelo diretório que irá receber os arquivos de backup. Estes arquivos podem ser bem grandes, cerca de 30% a 50% do espaço em disco atualmente ocupado pelo b-Cadastros. Logo no início o script verifica se o destino indicado nesse argumento possui a capacidade necessária para receber os arquivos que serão gerados e é recomendável a utilização de um armazenamento externo.
Se o backup foi realizado corretamente, ao final da execução do script é exibida a mensagem: "Backup realizado com sucesso em DESTINO!" (sendo DESTINO o diretório informado). Neste momento deve ser desmontada e desconectada a área de armazenamento externo, com o conteúdo do backup.
O próximo passo é restaurar o peer b-Cadastros no novo servidor com sistema atualizado. É fortemente recomendável desligar o servidor com CentOS 7 antes do procedimento de restauração no novo servidor. Somente após a restauração completa e a verificação de que está tudo funcionando com o novo peer, o antigo com CentOS 7 deve ser descartado, conforme o procedimento da seção Desativação do peer CentOS 7.
Restauração do peer em um novo servidor
Antes de iniciar o procedimento de restore, conecte a área de armazenamento externo com o conteúdo do backup no novo servidor que irá se tornar o peer. O ponto de montagem desta área será indicado como diretório de origem para o script de restore.
Atenção!
Para a realização deste procedimento, deve ser utilizado o script de restore fornecido por esta documentação.
O script de restore é mais complexo que o de backup, pois além de restaurar os dados que foram copiados no passo anterior, ele também instala todos os pré-requisitos de software necessários para a execução do peer b-Cadastros. Não serão listados todos os passos deste script, mas ele basicamente:
- Verifica se há espaço em disco suficiente para restaurar os volumes Docker do peer e do CouchDB;
- Verifica uma série de requisitos de conectividade e configuração, semelhantes aos verificados durante a instalação de um peer;
- Instala os softwares e as dependências necessárias para a execução dos serviços b-Cadastros;
- Realiza a descompactação e a restauração dos arquivos de backup em seus locais de destino, a saber:
/etc/hyperledger/var/lib/docker/volumes/peer_couchdata/var/lib/docker/volumes/peer_peerdata/var/opt/bcadastros
- Restaura a imagem da aplicação de monitoração (
appmon); - Inicia os serviços do b-Cadastros no peer novo;
Durante a descompactação dos arquivos do passo 4 será utilizado o algoritmo de compactação de acordo com a extensão dos arquivos de backup. Caso os arquivos de backup tenham a extensão zst, deve-se instalar o pacote zstd no servidor com o comando dnf -y install zstd antes da execução do script de restore.
O passo 4 deste script de restore é o mais demorado, embora seja mais rápido que o passo 3 do script de backup. Todo esse procedimento deve ser realizado com o peer antigo parado.
O diretório de origem dos arquivos de backup, que é o ponto de montagem da área de armazenamento externa, deve ser passado por argumento para o script de restore, caso contrário será utilizado o diretório /var/bkp como origem padrão.
O script de restore deve ser baixado e executado da seguinte forma, no novo servidor:
sudo dnf -y install zstd
# Instala o pacote zstd, requisito caso o backup tenha sido compactado com este algoritmo de compactação.
curl -k -s "https://s3.i02.estaleiro.serpro.gov.br/bcad-prod-publico/backup/restore-peer.sh" -o restore-peer.sh
# Baixa o script de restore para um arquivo com nome `restore-peer.sh`
sudo bash restore-peer.sh ORIGEM
# Executa o restore utilizando os arquivos disponíveis em `ORIGEM` (ex. /mnt/disco_externo)
# Caso não seja indicada a ORIGEM, é utilizado o diretório `/var/bkp` por padrão
Substitua o termo ORIGEM pelo diretório que contém os arquivos de backup. Logo no início o script verifica se a origem indicada nesse argumento possui os arquivos necessários para a restauração, assim como o espaço em disco necessário para tal.
Se a restauração foi realizada corretamente, ao final da execução do script é exibida a mensagem "Peer restaurado com sucesso!" e mais algumas dicas com comandos para verificação. Neste momento pode ser desmontada e desconectada a área de armazenamento externo, com o conteúdo do backup.
O próximo passo é verificar o peer b-Cadastros no novo servidor, com sistema atualizado. Somente após a verificação, o peer antigo deve ser descartado, de acordo com o procedimento documentado.
Verificação do correto funcionamento do novo peer
Por fim, verifique se os contêineres estão em execução no novo peer com o comando:
A lista deve ser similar à abaixo e o status dos contêineres deve ser "Up
IMAGE STATUS NAMES
monitoracao/appmon:latest Up 4 seconds appmon
nginx:1.22 Up 4 seconds nginx
hyperledger/fabric-peer:2.4.7 Up 4 seconds <nome_do_peer>
couchdb:3.2.2 Up 4 seconds couchdb
hyperledger/fabric-tools:2.4.7 Up 4 seconds cli
Verifique o log do peer com o comando:
Devem aparecer linhas semelhantes a:
2024-03-19 13:16:06.807 UTC 0001 INFO [nodeCmd] serve -> Starting peer:
Version: 2.4.7
Commit SHA: df9c661
Go version: go1.18.7
OS/Arch: linux/amd64
Chaincode:
Base Docker Label: org.hyperledger.fabric
Docker Namespace: hyperledger
2024-03-19 13:16:06.808 UTC 0002 INFO [peer] getLocalAddress -> Auto-detected peer address: 172.20.0.5:7051
2024-03-19 13:16:06.808 UTC 0003 INFO [peer] getLocalAddress -> Host is 0.0.0.0 , falling back to auto-detected address: 172.20.0.5:7051
2024-03-19 13:16:06.810 UTC 0004 INFO [nodeCmd] initGrpcSemaphores -> concurrency limit for endorser service is 2500
2024-03-19 13:16:06.810 UTC 0005 INFO [nodeCmd] initGrpcSemaphores -> concurrency limit for deliver service is 2500
2024-03-19 13:16:06.810 UTC 0006 INFO [nodeCmd] initGrpcSemaphores -> concurrency limit for gateway service is 500
2024-03-19 13:16:06.810 UTC 0007 INFO [nodeCmd] serve -> Starting peer with TLS enabled
2024-03-19 13:16:06.849 UTC 0008 INFO [certmonitor] trackCertExpiration -> The enrollment certificate will expire on 2032-12-06 12:24:15 +0000 UTC
2024-03-19 13:16:06.849 UTC 0009 INFO [certmonitor] trackCertExpiration -> The server TLS certificate will expire on 2025-09-07 23:37:29 +0000 UTC
2024-03-19 13:16:06.849 UTC 000a INFO [ledgermgmt] NewLedgerMgr -> Initializing LedgerMgr
2024-03-19 13:16:07.121 UTC 000b INFO [ledgermgmt] NewLedgerMgr -> Initialized LedgerMgr
2024-03-19 13:16:07.123 UTC 000c WARN [gossip.gossip] New -> External endpoint is empty, peer will not be accessible outside of its organization
2024-03-19 13:16:07.123 UTC 000d INFO [lifecycle] InitializeLocalChaincodes -> Initialized lifecycle cache with 0 already installed chaincodes
2024-03-19 13:16:07.124 UTC 000e INFO [nodeCmd] computeChaincodeEndpoint -> Entering computeChaincodeEndpoint with peerHostname: 172.20.0.5
2024-03-19 13:16:07.124 UTC 000f INFO [nodeCmd] computeChaincodeEndpoint -> Exit with ccEndpoint: 172.20.0.5:7052
2024-03-19 13:16:07.125 UTC 0010 INFO [sccapi] DeploySysCC -> deploying system chaincode 'lscc'
2024-03-19 13:16:07.126 UTC 0011 INFO [sccapi] DeploySysCC -> deploying system chaincode 'cscc'
2024-03-19 13:16:07.126 UTC 0012 INFO [sccapi] DeploySysCC -> deploying system chaincode 'qscc'
2024-03-19 13:16:07.126 UTC 0013 INFO [sccapi] DeploySysCC -> deploying system chaincode '_lifecycle'
2024-03-19 13:16:07.126 UTC 0014 INFO [nodeCmd] serve -> Deployed system chaincodes
2024-03-19 13:16:07.126 UTC 0015 INFO [peer] Initialize -> Loading chain chcaepf
2024-03-19 13:16:07.126 UTC 0016 INFO [ledgermgmt] OpenLedger -> Opening ledger with id = chcaepf
2024-03-19 13:16:07.189 UTC 0017 INFO [lifecycle] update -> Updating cached definition for chaincode 'bcadastros' on channel 'chcaepf'
2024-03-19 13:16:07.232 UTC 0018 INFO [ledgermgmt] OpenLedger -> Opened ledger with id = chcaepf
2024-03-19 13:16:07.264 UTC 0019 WARN [peer.orderers] Update -> Config defines both orderer org specific endpoints and global endpoints, global endpoints will be ignored channel=chcaepf
2024-03-19 13:16:07.265 UTC 001a INFO [deliveryClient] StartDeliverForChannel -> This peer will retrieve blocks from ordering service (will not disseminate them to other peers in the organization) channel=chcaepf
2024-03-19 13:16:07.265 UTC 001b INFO [peer] Initialize -> Loading chain chcno
2024-03-19 13:16:07.265 UTC 001c INFO [ledgermgmt] OpenLedger -> Opening ledger with id = chcno
2024-03-19 13:16:07.317 UTC 001d INFO [lifecycle] update -> Updating cached definition for chaincode 'bcadastros' on channel 'chcno'
2024-03-19 13:16:07.362 UTC 001e INFO [ledgermgmt] OpenLedger -> Opened ledger with id = chcno
2024-03-19 13:16:07.385 UTC 001f INFO [peer.blocksprovider] DeliverBlocks -> Pulling next blocks from ordering service channel=chcaepf orderer-address=hom-orderer0.bcadastros.serpro.gov.br:443 nextBlock=680
2024-03-19 13:16:07.393 UTC 0020 WARN [peer.orderers] Update -> Config defines both orderer org specific endpoints and global endpoints, global endpoints will be ignored channel=chcno
2024-03-19 13:16:07.396 UTC 0021 INFO [deliveryClient] StartDeliverForChannel -> This peer will retrieve blocks from ordering service (will not disseminate them to other peers in the organization) channel=chcno
2024-03-19 13:16:07.396 UTC 0022 WARN [nodeCmd] serve -> Discovery service must be enabled for embedded gateway
2024-03-19 13:16:07.396 UTC 0023 INFO [nodeCmd] serve -> Starting peer with ID=[peer.bcadastros.orgao.gov.br], network ID=[dev], address=[172.20.0.5:7051]
2024-03-19 13:16:07.396 UTC 0024 INFO [nodeCmd] serve -> Started peer with ID=[peer.bcadastros.orgao.gov.br], network ID=[dev], address=[172.20.0.5:7051]
2024-03-19 13:16:07.396 UTC 0025 INFO [kvledger] LoadPreResetHeight -> Loading prereset height from path [/var/hyperledger/production/ledgersData/chains]
2024-03-19 13:16:07.501 UTC 0026 INFO [peer.blocksprovider] DeliverBlocks -> Pulling next blocks from ordering service channel=chcno orderer-address=hom-orderer2.bcadastros.serpro.gov.br:443 nextBlock=1158
Caso apareçam erros de conexão e TLS, verifique se os IPs de saída para a Internet utilizados pelo novo peer são os mesmos utilizados pelo antigo peer. Caso sejam diferentes, notifique a mudança de IPs ao Serpro através do formulário de pedido de suporte.
Verifique também se suas aplicações que utilizam ou se integram ao peer estão configuradas e continuam funcionando corretamente com a nova instância.
Reversão em caso de falhas (rollback)
Caso haja algum problema no procedimento de restore no novo peer, o serviço pode ser reestabelecido apenas desligando o peer novo e religando o peer antigo, com CentOS 7. Caso tenha enfrentado problemas, acione o suporte do b-Cadastros.
Desativação do peer CentOS 7
Importante:
Para garantir o correto funcionamento da nova instalação e a continuidade do recebimento de novos dados dos canais contratados, o peer antigo (baseado em CentOS 7) não deve funcionar em paralelo com o novo e deve ser desativado por completo.
Após garantido o correto funcionamento do novo peer, o antigo pode ser completamente descartado, seja eliminando a máquina (física ou virtual) ou executando os comandos abaixo: