O que é o vStack Center

O vStack Center é o plano de gerenciamento de um cluster vStack Hyperconverged Infrastructure (doravante chamado de vStack HCP). Os administradores o usam para criar data centers virtuais (VDCs), redes e máquinas virtuais (VMs), atribuir papéis e consultar o log de eventos de segurança e as métricas. As próprias VMs são executadas no hipervisor dos nós do cluster. O vStack Center mantém o estado oficial do cluster e decide o que deve ser executado e onde.

O vStack HCP é um produto abrangente com duas partes: o vStack Center cuida do gerenciamento, e o vStack OS fornece o sistema operacional dos nós, incluindo o hipervisor e a camada de armazenamento. O vStack Center não interage diretamente com os nós. Ele envia uma tarefa ao Cluster Manager, que a entrega aos nós. Essa separação se reflete no comportamento da API: uma operação de VM envolve uma troca entre o vStack Center e os agentes nos nós, e não uma única gravação no banco de dados. Os nós, sua instalação, os requisitos de hardware e a CLI dos nós estão descritos na documentação do vStack OS.

Um cluster gerenciado pelo vStack Center opera de forma independente. Um produto separado, o GI, agrupa vários clusters em uma federação e encaminha solicitações a eles por proxy, mas o cluster não tem conhecimento disso: o conjunto de métodos e as regras de acesso permanecem os mesmos.

Dois componentes

O vStack Center é composto por dois serviços. Um aceita solicitações externas; o outro as executa.

Componente	O que faz	Com o que trabalha
cluster-endpoint	O endpoint HTTPS do cluster. Aceita solicitações HTTP POST com corpo JSON-RPC 2.0, coloca cada solicitação em fila, aguarda a resposta e a devolve ao cliente. Mantém sessões baseadas em cookies. Encaminha por proxy as conexões WebSocket para o console da VM	RabbitMQ, o navegador do cliente
dispatcher-cluster	O núcleo do vStack Center. Lê as solicitações da fila, verifica permissões, acompanha entidades e operações assíncronas e encaminha o trabalho aos agentes	PostgreSQL, SQLite, InfluxDB, Cluster Manager via ZMQ

O cliente vê apenas o primeiro componente: um endereço HTTPS e um formato de corpo. Todo o resto fica oculto atrás da fila.

Caminho da solicitação

Клиент → cluster-endpoint (HTTPS) → RabbitMQ → dispatcher-cluster → PostgreSQL / SQLite / InfluxDB
                                                        │ ZMQ
                                                        └→ Cluster Manager → узлы кластера (AMQP)

Клиент → cluster-endpoint (WSS) → VNC-сервер ВМ

O diagrama tem duas implicações práticas. Primeiro, o cluster-endpoint não armazena o estado das operações da aplicação, portanto pode ser reiniciado e escalado separadamente do núcleo. Segundo, o tráfego do console da VM não passa pela fila: ele trafega por WebSocket, diretamente pelo endpoint até o servidor VNC da máquina.

Um protocolo para tudo

O vStack Center usa apenas JSON-RPC 2.0: cada operação tem um nome, seu próprio conjunto de argumentos e um formato de resposta consistente. A interface web segue o mesmo caminho que um cliente personalizado; o vStack Center não tem uma interface separada para a interface web. Como resultado, tudo o que um administrador faz com o mouse também pode ser feito programaticamente. Por isso, as páginas de procedimentos desta documentação listam, ao final, os métodos de API para as mesmas operações.

A estrutura da resposta é a mesma para todos os métodos. Uma resposta de sucesso contém o payload da operação específica: um objeto, um array ou um valor único. Uma resposta de falha contém um código numérico. Os códigos são agrupados por método, então o número identifica onde a solicitação parou. Os formatos de solicitação e resposta estão descritos na referência Visão geral da API.

Sessão

O dispatcher não obtém a identidade de quem faz a chamada a partir do transporte. Ele identifica quem faz a chamada por um token de sessão: a interface web recebe um token no login e o apresenta em cada operação, e um cliente personalizado deve fazer o mesmo. O dispatcher rejeita solicitações sem token antes de executar a lógica da aplicação, com o código -9494 ("No session token").

A troca obrigatória de senha segue um caminho separado. Um usuário com esse sinalizador recebe um acesso único válido por 5 minutos em vez de uma sessão regular. Até que a senha seja alterada, ficam disponíveis apenas a própria troca de senha e a leitura da política de senhas. Por isso, a interface web exibe imediatamente o formulário de nova senha, e as demais seções ficam disponíveis após a troca. Os formatos de token e os campos de resposta estão descritos na referência Autenticação.

Quem pode ver o quê

As permissões no vStack Center são definidas por um papel e seu escopo: o cluster ou um VDC específico. As seções de métodos descrevem o acesso nos mesmos termos: "Cluster master — qualquer VM do cluster" e "usuário comum — apenas VMs nos VDCs em que há papéis atribuídos".

id	Papel	Escopo
1	Cluster Master	Acesso total a todo o cluster
2	vDC Admin	Administrador do VDC
3	vDC User	Usuário do VDC
4	vDC Viewer	Visualizador do VDC
5	Resource Viewer	Visualização dos recursos do cluster
6	Security Admin	Nível do cluster: log de segurança e auditoria
7	VM Developer	Nível do VDC: criar e configurar máquinas virtuais

As operações de gerenciamento de VDC, ou seja, criação, modificação e exclusão, estão disponíveis apenas para Cluster Master. O trabalho dentro de um VDC é delegado por meio dos papéis 2–4 e 7. Os papéis 6 e 7 foram introduzidos na 3.0.3.

Métodos síncronos e assíncronos

Alguns métodos respondem imediatamente porque apenas leem ou gravam no banco de dados. Por exemplo, vm-console retorna os detalhes de conexão sem contatar um nó. Outros métodos respondem depois que um agente confirma que o trabalho foi concluído.

O vms-create segue uma longa sequência: validação de parâmetros, seleção do pool, gravação no banco de dados, repasse ao agente Storage para criar os zvols e, em seguida, repasse ao agente VM para o registro. O cliente recebe a resposta após o processamento de callback em duas fases, e a resposta contém uma descrição completa da VM criada. O vms-start funciona da mesma forma: o método envia um comando ao agente, e a resposta final chega por meio de um callback e contém data.node_id, o nó em que a VM foi iniciada.

A implicação prática é que o cliente precisa ser capaz de esperar. Defina o tempo limite da solicitação com base na duração da operação real no nó, e não na velocidade do banco de dados.

O que saber antes de começar

Uma solicitação sem token de sessão não será processada. Motivo: o dispatcher identifica quem faz a chamada apenas pelo token de sessão; os cabeçalhos de transporte não são usados para isso. Solução alternativa: apresente o token em todas as chamadas da aplicação; caso contrário, a resposta conterá o código -9494.

Algumas operações terminam depois que a resposta é retornada. Motivo: os agentes nos nós executam o trabalho, e o dispatcher apenas aguarda seus callbacks. Solução alternativa: confie na resposta final do método, e não na primeira, e reserve tempo extra no tempo limite do cliente.

Uma imagem de SO que não está visível retorna "não encontrado" em vez de "acesso negado". Motivo: a existência de uma imagem privada pertencente a outro VDC não é revelada. Se você tentar selecioná-la, o vms-create retorna -256. Solução alternativa: use uma imagem compartilhada no cluster (is_cluster_shared) ou solicite uma concessão de visibilidade da imagem necessária para o seu VDC.

Próximos passos

O caminho completo do login até uma VM em execução é abordado no início rápido: criação de um VDC, atribuição de uma rede, criação e inicialização de uma máquina e conexão ao seu console.