Adesão de streamers¶

cluster.control.nodes

O central armazena a configuração do cluster e determina quais streams cada streamer executa. Para adicionar uma máquina, o operador abre uma janela de adesão e fornece à máquina o endereço do central e o token de adesão. Após o registro, o streamer recebe uma identidade persistente, sincroniza a configuração e informa seu estado.

Não é necessário copiar a configuração de todos os streams para o novo servidor. O central entrega as atribuições; o operador gerencia a máquina pelas configurações do streamer. Consulte a instalação para implantar o Sapsan.

Requisitos¶

São necessários:

• Endereço do central: endereço HTTP ou HTTPS do grupo de gerenciamento acessível ao streamer.
• Token de adesão: segredo de uma janela ativa obtido pelo operador no central.
• Diretório de estado persistente: diretório gravável preservado após reiniciar o processo ou contêiner.
• Instalação compatível: a distribuição e a licença devem permitir a participação no cluster escolhido.

O streamer inicia a conexão de sincronização. As solicitações inversas do central e as leituras de mídia por outros streamers também exigem endereços corretos da máquina. Consulte conectividade e entrega.

Janela de adesão¶

A ação permit_join abre uma janela de uma hora e emite um token de adesão. Durante esse prazo, streamers com o token podem se registrar. É uma permissão temporária para criar um registro, não a senha permanente do streamer. Não há aprovação manual de cada máquina: o token ativo permite o registro.

Abra a janela pela API de gerenciamento do central com uma chave administrativa:

curl -fsS -X POST \
  -H "Authorization: Bearer $ADMIN_KEY" \
  https://central.example/central/api-v4/nodes/permit-join

A solicitação não exige corpo. A resposta contém o token em token, o estado em open e os segundos restantes em remaining_secs. Guarde o token para as máquinas novas. Um GET comum no mesmo endereço não revela o segredo; para recuperá-lo enquanto a janela estiver ativa, use GET /central/api-v4/nodes/permit-join/reveal com autenticação administrativa.

Repetir permit_join com a janela aberta a estende mantendo o mesmo token. Abrir uma janela após seu fechamento ou expiração gera outro token. A extensão mantém o token já entregue às máquinas em instalação.

Um token permite adicionar vários streamers. Feche a janela ao terminar. O fechamento ou a expiração não revogam registros existentes: os streamers já associados continuam a sincronização com suas próprias credenciais.

curl -fsS -X DELETE \
  -H "Authorization: Bearer $ADMIN_KEY" \
  https://central.example/central/api-v4/nodes/permit-join

O streamer repete as tentativas de registro inicial recusadas. Verifique se a janela está aberta e se a máquina usa seu token atual. Se a janela anterior expirou, forneça o token novo aos streamers ainda não registrados.

Ativar o modo gerenciado¶

Configure a conexão localmente em managed_by:

managed_by:
  url: https://central.example
  name: streamer-01
  join_token: "JOIN_TOKEN_FROM_CENTRAL"
  state_dir: /var/lib/sapsan/central

O endereço do grupo pode ser uma lista:

managed_by:
  url:
    - https://central-1.example
    - https://central-2.example
  join_token: "JOIN_TOKEN_FROM_CENTRAL"

A lista estabelece a preferência dos endereços. Em caso de falha de rede, o streamer tenta outros endereços do grupo. Também preserva os endereços recebidos do central para usá-los após reiniciar. Não misture clusters independentes: são entradas alternativas para o mesmo grupo.

Sem esquema, acrescenta-se http://. Para TLS, indique https:// e configure o certificado do servidor.

As mesmas opções podem ser definidas no ambiente:

O ambiente prevalece sobre os valores correspondentes da configuração. Remova variáveis antigas ao mover a instalação para outro cluster.

managed_by ativa o modo gerenciado. A seção central configura o próprio componente de gerenciamento e não substitui managed_by. Não é permitido combinar managed_by com a fonte externa de configuração config_external.

Identidade persistente¶

O registro retorna node_id e o segredo node_key. O streamer os salva em identity.json, dentro de state_dir, para as próximas sincronizações. node_id é o identificador da API; nem name nem o hostname constituem essa identidade.

Em uma reinicialização normal, o streamer carrega sua identidade sem se registrar novamente. Não precisa de outra janela mesmo após o token antigo expirar. Alterar o rótulo também não cria outro registro.

Preserve o diretório ao atualizar ou recriar o contêiner. Perder identity.json significa perder as credenciais; um arquivo corrompido causa um erro em vez de criar outro registro silenciosamente. Copiá-lo para outra máquina transfere a mesma identidade, não adiciona um novo streamer.

O arquivo contém um segredo e é criado com permissões 0600. Restrinja o acesso ao processo e aos administradores. Não inclua identidades ou tokens em relatórios públicos de diagnóstico.

Autenticação nas duas direções¶

Gerenciamento e leitura de mídia usam credenciais diferentes:

Cada direção tem seu mecanismo de autorização. Isso não configura automaticamente TLS mútuo. Com HTTPS, o cliente verifica o certificado do servidor pelo mecanismo normal de TLS; a adesão não fixa uma chave especial do central nem emite certificado de cliente.

Verifique o endereço e use HTTPS ou uma rede protegida para transmitir segredos de gerenciamento. Possuir um token de adesão não autentica por si só o servidor central de destino.

Os bilhetes entre servidores são assinados com Ed25519 e verificados localmente. A validade atual é de 24 horas; o central os renova antes da expiração. Um bilhete salvo e válido permite leituras de outros streamers durante uma interrupção temporária, mas não concede acesso indefinido sem renovação.

Quem controla a configuração¶

No modo gerenciado, o central determina a lista de streams: o campo local streams não se combina com as atribuições nem vira reserva ao perder a conexão. Crie streams e altere sua distribuição pelo central. Consulte a distribuição de streams.

As configurações do servidor têm várias camadas. O central entrega os parâmetros, mas arquivos include locais e o ambiente podem sobrescrever valores individuais. O valor salvo no central pode diferir do efetivo na máquina. A interface indica essas sobrescritas; consulte a ordem de aplicação.

Atualize a configuração e acompanhe sua aplicação pelo central. Na máquina permanecem o endereço do grupo e os parâmetros de inicialização necessários à conexão.

Quando o central fica indisponível¶

O streamer salva em disco as configurações e seu slice de streams. Os streams já aplicados continuam funcionando durante perdas temporárias da conexão de gerenciamento; uma lista local não substitui a configuração.

Após reiniciar, pode restaurar a operação pelo cache e retomar a sincronização. Sem cache utilizável, como na primeira inicialização, precisa do central para receber atribuições. O token de adesão não contém configurações de streams.

A recusa de node_key também não transforma o streamer em um membro novo: ele informa o erro e mantém a configuração aplicada. Restaurar a conexão exige ação do operador. Abrir outra janela não corrige um registro existente.

O cache não transforma o streamer em um plano de controle independente. Novas atribuições e alterações aguardam o retorno da conexão; os bilhetes expiram. A continuidade depende também das fontes, dos discos e dos demais streamers.

Verificar a adesão¶

Após iniciar, verifique:

1. O streamer aparece no registro do central com o rótulo esperado e o estado atual da conexão.
2. O diretório persiste após reiniciar e o mesmo registro é reutilizado.
3. O central alcança o endereço da API e os outros streamers alcançam o endereço privado de entrega.
4. As configurações são entregues e confirmadas como aplicadas; o ambiente não sobrescreve os valores necessários.
5. Os streams atribuídos funcionam e as leituras entre servidores usam um bilhete válido.

Avalie a conexão e a aplicação de configuração separadamente da saúde da mídia. O registro não garante uma fonte acessível ou armazenamento saudável; perder o central também não interrompe imediatamente uma transmissão em andamento.