CLI do nó

Em um nó do vStack OS, o administrador precisa de dois utilitários:

• o utilitário do cluster vstack-cluster mostra os nós e os serviços do cluster, habilita e desabilita nós e inicia, para e move pools;
• o script de atualização vStack.update.sh atualiza os pacotes, o sistema base e o kernel do nó.

Ambos são executados como root no próprio nó. Máquinas virtuais, redes e VDCs são gerenciados pelo vStack Center; sua interface e sua API estão descritas na documentação do Center.

Utilitário do cluster

O vstack-cluster é o cliente do Cluster Manager (o daemon ccrd). Ele chega ao nó com o pacote vStack-ccrd e fica em /usr/local/bin. O utilitário não tem estado próprio: cada comando é enviado ao ccrd, e o utilitário imprime a resposta dele. Você pode executá-lo em qualquer nó do cluster.

Formato de chamada:

vstack-cluster <COMMAND> [<ACTION>] {OPTIONS}

Um nó é especificado pelo número (--id, --dst-id), um serviço pelo nome (-s, --service-name). O utilitário não aceita o nome de um nó no lugar do número. O número do nó está no intervalo 1–63.

Nós e serviços

• Nó — um servidor do cluster. Tem um número (Node ID) e um nome no formato q100u001.<domain>.
• Serviço — algo que o Cluster Manager posiciona em um dos nós. Cada pool de armazenamento zNN é representado pelo serviço zpool_zNN. O serviço cluster-management pertence ao próprio Cluster Manager: não o inicie, pare ou mova manualmente.

Um nó e um serviço têm, cada um, dois atributos independentes:

Atributo	Valores	Significado
state	nó: ONLINE, OFFLINE; serviço: STARTED, STOPPED, STOPPING e outros	o estado real no momento
[enabled] / [disabled]	—	se serviços podem ser posicionados no nó; se o serviço participa do posicionamento automático e do failover

Comandos

Comando	O que faz
status	os nós e os serviços em execução neles
node list	números dos nós
node status	o estado de todos os nós
node disable --id=N	fecha o nó para o posicionamento de serviços
node enable --id=N	abre o nó novamente
service list	nomes dos serviços
service status	o estado de todos os serviços e os nós em que são executados
service start -s <service> --id=N	inicia o serviço no nó N
service stop -s <service>	para o serviço
service move -s <service> --dst-id=N	move o serviço para o nó N
service enable -s <service>	devolve o serviço ao posicionamento automático
service disable -s <service>	exclui o serviço do posicionamento automático
ha disk status	o estado das reservas SCSI/NVMe nos discos do grupo de fencing de HA

O comando node exit remove um nó do cluster. Ele não pode ser desfeito, por isso não é descrito aqui: execute-o somente junto com o suporte técnico da vStack.

Opções comuns

Opção	O que faz
-h, --help	ajuda para o nível atual, por exemplo vstack-cluster service move --help
-v, --version	versão do utilitário
-c <file>, --config=<file>	um arquivo de configuração diferente. Geralmente não é necessário

status

Os nós do cluster e os serviços em cada um deles. Com --json, o mesmo conteúdo é exibido em JSON.

vstack-cluster status

Node ID:  1; name:   q100u001.example.com; state:       ONLINE; [     enabled]
	Service name:                zpool_z02; state:    STARTED; [     enabled]

Node ID:  2; name:   q100u002.example.com; state:       ONLINE; [     enabled]
	Service name:       cluster-management; state:    STARTED; [     enabled]
	Service name:                zpool_z03; state:    STARTED; [     enabled]

Node ID:  3; name:   q100u003.example.com; state:       ONLINE; [     enabled]

Node ID:  4; name:   q100u004.example.com; state:       ONLINE; [     enabled]
	Service name:                zpool_z01; state:    STARTED; [     enabled]
	Service name:                zpool_z04; state:    STARTED; [     enabled]

Um nó sem nenhum serviço, como o q100u003 no exemplo, é normal para um nó que falhou e voltou. O Cluster Manager move os pools para fora de um nó com falha, mas não os devolve sozinho. Você pode devolver um pool com o comando service move ou pelo vStack Center.

vstack-cluster status --json

{
   "cluster": {
      "nodes": [
         { "enabled": true, "id": 1, "name": "q100u001.example.com", "state": "ONLINE" }
      ],
      "services": [
         { "enabled": true, "name": "zpool_z02", "nodeId": 1, "state": "STARTED" }
      ]
   }
}

services[].nodeId é o número do nó no qual o serviço é executado.

node list, node status

node list imprime somente os números dos nós; node status imprime números, nomes e estado.

vstack-cluster node status

Node ID:  1; name:   q100u001.example.com; state:     ONLINE; [     enabled]
Node ID:  2; name:   q100u002.example.com; state:     ONLINE; [     enabled]

node disable, node enable

disable fecha o nó para o posicionamento de serviços; enable o abre novamente.

vstack-cluster node disable --id=2
vstack-cluster node enable --id=2

cuidado

Após disable, os serviços permanecem no nó, e o comando parece não fazer nada. Mas na próxima mudança na composição do cluster, por exemplo depois que qualquer nó reinicializar, o Cluster Manager recalcula o posicionamento e move os serviços para fora de todos os nós fechados. Se restar apenas um nó aberto, todos os pools do cluster serão movidos para ele.

Feche no máximo um nó por vez e abra-o assim que terminar o trabalho. Para mover um pool, use service move, e não node disable.

service list, service status

service list imprime somente os nomes dos serviços. service status mostra o estado de cada um e o número do nó em que é executado.

vstack-cluster service status

Service name:       cluster-management; state:    STARTED at node:  2; [     enabled]
Service name:                zpool_z01; state:    STARTED at node:  4; [     enabled]
Service name:                zpool_z02; state:    STARTED at node:  1; [     enabled]

Não é possível selecionar um único serviço ou um único nó em status; filtre a saída, por exemplo vstack-cluster service status | grep zpool_z01.

service start, service stop

stop para o serviço no nó em que ele é executado. start inicia um serviço parado no nó especificado.

vstack-cluster service stop -s zpool_z03
vstack-cluster service start -s zpool_z03 --id=3

Parar um serviço de pool significa exportar o pool: as VMs desse pool param, e o fornecimento dos seus volumes cessa.

service move

Move um serviço para outro nó. Não é necessário especificar o nó de origem.

vstack-cluster service move -s zpool_z01 --dst-id=2

Opção	Obrigatória	O que define
-s, --service-name	sim	nome do serviço
--dst-id	sim	número do nó de destino, 1–63

O nó de destino deve estar ONLINE e aberto (enabled). Durante a movimentação, as VMs do pool e o fornecimento dos seus volumes são interrompidos. O pool no qual a VM de gerenciamento (vStack Center) é executada só pode ser movido com este comando: ele não pode ser movido pela interface do Center. O procedimento está descrito na seção "Mover o pool com a VM de gerenciamento".

Se o serviço parou, mas não iniciou no novo nó, o utilitário não o move de volta. Verifique o estado com o comando service status e, enquanto o serviço não estiver STARTED, entre em contato com o suporte técnico.

service enable, service disable

enable devolve o serviço ao posicionamento automático; disable o exclui dele.

vstack-cluster service enable -s zpool_z03

Após enable, o Cluster Manager recalcula o posicionamento e pode imediatamente iniciar o serviço por conta própria.

Códigos de saída

Código	Significado
0	o comando foi concluído
12	um comando desconhecido, uma opção desconhecida ou falta uma opção obrigatória. O utilitário imprime o motivo e a ajuda

ccrd_cli

O ccrd_cli é instalado no nó junto com o ccrd. Sem argumentos, ele imprime o mesmo que vstack-cluster status. Para trabalhar com o cluster, use o vstack-cluster.

vStack.update.sh

O script de atualização do nó. Ele fica em /root/bin/vStack.update.sh e atualiza os pacotes a partir do repositório da vStack: controladores, o sistema base e o kernel. O procedimento de atualização, as verificações e a reversão estão descritos na página "Atualização do nó para a 3.2".

vStack.update.sh {--controllers | --base} [OPTIONS]

Exemplo

/root/bin/vStack.update.sh --controllers --base --source release --version 3.2.0 --dry-run

O que atualizar

Pelo menos uma das duas opções é obrigatória; caso contrário, o script termina com o código 1.

Opção	O que atualiza
--controllers	pacotes do nó, exceto o sistema base
--base	o sistema base e o kernel, e também os controladores. Depois disso, o nó deve ser reinicializado

De onde obter os pacotes

Opção	Valor	O que define
--source	release	o repositório de releases da vStack. Para nós de clientes, é a origem padrão. Requer --version
--source	local	um repositório local no nó, file:///local/repos/vstack/...
--version	X.Y.Z ou X.Y.Z-rcN	a versão da distribuição, por exemplo 3.2.0
--repo-url	URL	um endereço de repositório diferente, por exemplo um espelho interno

O acesso ao repositório de releases é concedido por uma lista de permissões de endereços. Envie os endereços dos nós para essa lista ao suporte técnico da vStack.

Como atualizar

Opção	O que faz
--dry-run	mostra o plano e não altera nada
--no-restart	não reinicia os serviços após a atualização. Útil se uma reinicialização vier em seguida
--reboot	reinicializa o nó após atualizar o sistema base e o kernel. Ignorada com os códigos 6 e 7
--log PATH	caminho do log. Padrão: /var/log/vstack-os-update-<ts>.log
-h, --help	ajuda

Proteção de inicialização

Por padrão, o script salva o kernel anterior em <kernel directory>_prev, inicializa o novo uma única vez com reversão automática para o anterior e atualiza o bootloader na partição EFI. O bootloader é copiado somente para a partição EFI a partir da qual o nó está inicializado no momento; ele não chega ao segundo disco de sistema.

As opções abaixo desativam essas proteções. Não as use a menos que o suporte instrua.

Opção	O que desativa
--no-kernel-backup	a cópia do kernel anterior. Sem ela, o script não para se não houver espaço suficiente para a cópia
--no-fallback	a inicialização única do novo kernel com reversão automática
--no-esp	a atualização do bootloader na partição EFI

Passagem entre versões principais

Necessária somente na passagem da linha 2.x para a 3.x, e feita junto com o suporte técnico da vStack.

Opção	O que faz
--allow-major-upgrade	permite a passagem entre versões principais. Sem ela, o script rejeita essa passagem com o código 2. Não é necessária para uma atualização comum dentro de uma linha
--install-missing	instala adicionalmente todos os pacotes do release de destino que faltam no nó
--rename-map PATH	um mapa de pacotes renomeados. Obtido da distribuição por padrão

Códigos de saída

Código	Significado
0	a atualização foi concluída
1	um erro nos argumentos
2	a origem ou a versão não está disponível, a chave de assinatura não foi obtida, ou foi solicitada uma passagem entre versões principais sem --allow-major-upgrade
3	um erro do pkg ou um erro na verificação do novo kernel. Não haverá reinicialização
4	falha ao salvar ou restaurar a configuração: /etc, /usr/local/etc, vstack-env.conf, arquivos de inicialização em /boot
5	um serviço instalado não reiniciou
6	a atualização foi concluída, mas o shell do root não é executável. Corrija antes de reinicializar; caso contrário, o root não conseguirá entrar por ssh
7	a atualização foi concluída, mas a gravação em /boot não foi confirmada. Não reinicialize até investigar

Arquivos

Caminho	O que contém
/var/backups/etc-<ts>/	uma cópia de /etc; os subdiretórios usr-local-etc e boot contêm cópias de /usr/local/etc e dos arquivos loader.conf, loader.conf.local, device.hints. As cinco mais recentes são mantidas
/var/backups/vstack-env-<ts>.conf	uma cópia do vstack-env.conf
/var/backups/update-summary-<ts>.txt	o resumo final da execução
/var/log/vstack-os-update-<ts>.log	o log completo
/boot/nextboot.conf, /boot/loader.conf.d/zz-vstack-fallback.conf	inicialização única do novo kernel e reversão. Após uma inicialização bem-sucedida, o próprio nó os remove