Conectar um cluster Kubernetes

Um cluster Kubernetes inteiro pode ser um servidor no portal. Você instala dois componentes no namespace scolah-system, cada um com seu próprio chart Helm:

O agente (scolah-agent) se conecta à plataforma, baixa e verifica cada bundle de aplicativo e registra o que deve rodar no cluster. Ele mesmo não inicia nenhuma carga de trabalho.
O operador (scolah-operator) faz o trabalho. Ele verifica novamente, por conta própria, a assinatura de cada bundle e depois cria as cargas de trabalho, os volumes e as rotas web do aplicativo.

Os dois compartilham um volume, scolah-agent-bundles. O agente coloca nele os bundles verificados e o operador os lê a partir dele. Um cluster executa exatamente um agente e um operador.

Você precisa ser Administrador da organização para registrar o servidor e ter direitos de administrador no cluster para instalar os charts.

Antes de começar

Cluster

Kubernetes com Helm 3 e kubectl. Testamos no Kubernetes 1.37. Os charts não definem uma versão mínima.
Uma StorageClass padrão. Os charts criam dois volumes: um volume de 10 GiB para os bundles e um volume de 1 GiB para a identidade do agente. Os aplicativos criam seus próprios volumes para os dados. Nenhum deles especifica uma storage class, por isso é usada a padrão do cluster.
Em um cluster com mais de um nó, o volume dos bundles é ReadWriteOnce por padrão, então o agente e o operador precisam rodar no mesmo nó. Para que eles rodem em nós diferentes, use uma storage class que suporte ReadWriteMany e acrescente --set bundles.accessMode=ReadWriteMany --set bundles.storageClass=<class> ao comando de instalação do agente.

Tráfego web

Um controlador de Ingress, como o ingress-nginx, se as pessoas forem acessar as instalações por um domínio. O operador dá a cada domínio um Ingress. Você não precisa de um para conectar o cluster nem para implantar aplicativos.
cert-manager e um ClusterIssuer se você quiser Let’s Encrypt (HTTPS automático) em um cluster. O operador não solicita certificados ele mesmo. Ele os solicita ao seu emissor.

Se o seu cluster tiver um Gateway (Kubernetes Gateway API), as instalações podem associar suas rotas a ele. Escolha Terminado pelo seu Gateway (Gateway API do Kubernetes) como modo TLS do domínio (consulte Domínios e HTTPS).

Rede

HTTPS de saída do pod do agente para o endereço da plataforma informado no comando de instalação.
Acesso de saída a partir dos nós para os registros de contêiner de onde vêm as imagens dos aplicativos. O cluster baixa as imagens em cada nó, não por meio do agente.
Nenhuma porta de entrada para conectar o cluster ou implantar aplicativos. Para os domínios, seu controlador de Ingress precisa estar acessível nas portas 80 e 443.

1. Registrar o cluster

Acesse Servidores e clique em Adicionar servidor.
Dê a ele um Nome que você reconheça, como cluster-nairobi.
Escolha Kubernetes como Ambiente. Não há sistema operacional para escolher.
Revise as configurações do cluster. O portal as coloca no comando de instalação:
- Classe de ingress: a classe do seu controlador de Ingress. Padrão: nginx.
- Namespace do controlador de ingress: o namespace onde roda seu controlador de Ingress. Padrão: ingress-nginx. O namespace de cada instalação bloqueia o tráfego de outros namespaces, e isto libera a passagem do seu controlador de Ingress.
- Serviço do controlador de ingress: o Service do seu controlador de Ingress. Padrão: ingress-nginx-controller. O agente informa o endereço de load balancer desse Service como endereço público do cluster, para seus domínios.
- Endereço público (opcional): o IP ou nome de host em que o controlador de Ingress do cluster pode ser acessado de fora, como 203.0.113.10. Defina-o quando o endereço do load balancer não for aquele que as pessoas alcançam, por exemplo atrás de NAT. Ele substitui o endereço detectado.
- Emissor de certificados (opcional): o ClusterIssuer do cert-manager para domínios com Let’s Encrypt (HTTPS automático), como letsencrypt. Sem ele, esses domínios não recebem rota.
Os nomes podem usar letras minúsculas, dígitos, - e ..
Clique em Criar.

Adicionar servidor, com Kubernetes selecionado

O portal mostra um Token de inscrição e um Comando de instalação.

O comando de instalação para um cluster Kubernetes

2. Instalar o agente e o operador

O comando de instalação instala os dois charts de uma só vez. Ele é parecido com isto:

helm install scolah-agent oci://ghcr.io/engineeringpurple/charts/scolah-agent \
  --namespace scolah-system --create-namespace \
  --set platformUrl=https://… --set enrollToken=spa_… \
  --set ingressService=ingress-nginx/ingress-nginx-controller \
&& helm install scolah-operator oci://ghcr.io/engineeringpurple/charts/scolah-operator \
  --namespace scolah-system \
  --set bundles.pvc=scolah-agent-bundles \
  --set platformReleaseKey=… \
  --set ingressClassName=nginx \
  --set ingressControllerNamespace=ingress-nginx

O release do agente cria o namespace scolah-system, o próprio agente e o volume compartilhado scolah-agent-bundles. O token é usado uma vez, quando o agente se inscreve.
O release do operador vai para o mesmo namespace. bundles.pvc aponta o operador para o volume criado pelo release do agente.
platformReleaseKey é a chave pública de assinatura da plataforma. O operador verifica cada bundle de aplicativo com ela antes de implantar.
ingressService (no agente) e ingressClassName e ingressControllerNamespace (no operador) vêm das configurações do cluster que você escolheu. Um Endereço público acrescenta --set publicAddress=… ao agente, e um Emissor de certificados acrescenta --set certManager.issuerRef.name=… ao operador.

Se o cluster ainda não tiver cert-manager, acrescente --set certManager.install=true à parte do operador para instalá-lo junto com o operador. Você ainda precisa criar o ClusterIssuer.

Para alterar as configurações do cluster mais tarde, abra o servidor e clique em Regenerar token: ele mostra as mesmas configurações acima de um novo comando.

3. Confirmar que está conectado

Em até um minuto, o status do servidor no portal muda de Pendente para Conectado, e a versão do agente e os recursos do cluster aparecem.

Se isso não acontecer, verifique os pods e o log do agente:

kubectl -n scolah-system get pods
kubectl -n scolah-system logs statefulset/scolah-agent

Um agente funcionando registra enrolled e depois agent ready. Quando o operador inicia, ele registra uma linha PREFLIGHT para cada coisa que não consegue corrigir sozinho, como uma chave de release ausente, a falta do cert-manager ou a falta de uma credencial de registro. Essas linhas não impedem a inicialização, mas indicam o que vai falhar mais tarde:

kubectl -n scolah-system logs deploy/scolah-operator | grep PREFLIGHT

O agente armazena sua identidade no próprio volume, por isso não precisa mais do token. Uma atualização com helm upgrade também não precisa de token.

O que cada instalação recebe

Crie instalações no cluster da mesma forma que em um servidor Docker: escolha o cluster na lista Servidor do assistente. Para cada instalação, o cluster recebe:

Um namespace com o nome do aplicativo e o início do ID da instalação, como sample-nginx-21333d29. Tudo o que a instalação executa fica nele.
Um recurso Installation, com o ID da instalação como nome. Ele mostra o que o operador está fazendo:
Terminal window
```
kubectl get installations
```
Um Secret <app>-env com as configurações e as senhas do aplicativo. Só o agente consegue descriptografar o que a plataforma envia, por isso é ele que grava esse Secret.
NetworkPolicies que bloqueiam o tráfego de outros namespaces, exceto o do seu controlador de Ingress.
Para os aplicativos que usam as imagens privadas da Scolah (Scolah Compass, OpenEWS), um pull secret scolah-registry-auth com a credencial de registro da sua organização. O agente o grava e os pods o usam automaticamente, então você não precisa configurar uma credencial de registro no cluster.
Quando a instalação está protegida pela recuperação de desastres, um pull secret scolah-dr-agent-pull: uma cópia dos imagePullSecrets definidos no chart do agente, para que os pods de recuperação possam baixar a imagem do agente de um registro privado. Consulte Registros privados em um cluster.
As próprias cargas de trabalho, serviços e volumes do aplicativo.

Uma instalação rodando em um cluster Kubernetes

Uma instalação em um cluster não tem endereço enquanto você não adicionar um domínio. Em um servidor Docker, o portal mostra o endereço IP do servidor e uma porta. Um cluster não tem nenhum dos dois, por isso a caixa Acesso e domínios fica vazia.

As conexões também funcionam em um cluster. As duas instalações precisam estar no mesmo cluster.

Domínios e HTTPS

Adicione um domínio pela aba Domínios da instalação, como descrito em Domínios e HTTPS. Depois que o domínio é verificado, o operador cria um Ingress chamado scolah-route-<site> no namespace da instalação, e o remove quando você exclui o domínio.

O endereço público do cluster

O DNS dos domínios de um cluster aponta para o local onde seu controlador de Ingress pode ser acessado de fora. O agente informa esse endereço ao portal:

Se você definir um Endereço público (publicAddress no release Helm do agente), esse é o endereço usado.
Caso contrário, o agente lê o IP externo ou o nome de host do Service LoadBalancer do seu controlador de Ingress.

O portal então indica qual registro criar: um registro A quando o endereço é um IP, ou um CNAME quando é um nome de host (como acontece com frequência com load balancers na nuvem). Um Subdomínio Scolah cria esse registro para você.

Se o cluster ainda não tiver endereço público, por exemplo porque seu controlador de Ingress não está exposto por meio de um load balancer, a aba Domínios informa isso, e você não pode adicionar um subdomínio Scolah até que exista um. Exponha o controlador de Ingress por meio de um Service LoadBalancer ou defina publicAddress no release Helm do agente.

Modos TLS em um cluster

Modo TLS	Em um cluster
Let’s Encrypt (HTTPS automático)	O cert-manager obtém o certificado do emissor definido em `certManager.issuerRef.name`.
Usar seu próprio certificado	Clique em Adicionar certificado ao lado do domínio e cole o certificado e a chave. O agente os armazena em um Secret `scolah-tls-<site>`. O domínio não tem rota enquanto o certificado não estiver lá.
Sem TLS (atrás de um proxy externo)	O site é servido por HTTP simples.
Terminado pelo seu Gateway (Gateway API do Kubernetes)	Somente em clusters. A rota se associa a um Gateway que você já executa, que termina o HTTPS. Opcionalmente, informe o namespace, o nome e o listener do Gateway; deixe-os vazios para usar o Gateway padrão do operador. Aponte o nome de host para o endereço externo do seu Gateway.

O domínio está encaminhado?

Cada domínio na aba Domínios mostra Encaminhado assim que o cluster passa a servi-lo, ou Não encaminhado com o motivo, por exemplo um certificado ou emissor ausente. O status é atualizado sem uma nova aplicação: o operador verifica o domínio novamente assim que o Secret de certificado correspondente é adicionado ou removido, ou a rota correspondente é alterada ou excluída, e o agente informa a alteração na consulta seguinte, normalmente em menos de 30 segundos. Isso requer a versão mais recente do agente. Agentes mais antigos só atualizam o status quando a instalação é aplicada.

Remover uma instalação

Exclua uma instalação no portal normalmente. Em um cluster, o operador remove as cargas de trabalho e depois exclui o namespace da instalação, incluindo seus volumes e dados. Em seguida, exclui o recurso Installation.

Não exclua uma Installation com kubectl. A plataforma é a fonte da verdade, por isso o agente a grava novamente e o operador inicia de novo o aplicativo sobre os volumes preservados.

Desconectar o cluster

Exclua no portal todas as instalações do cluster. O portal não exclui um servidor que ainda tenha instalações.
Abra o servidor e clique em Excluir.

Desinstale os dois charts:

helm uninstall scolah-operator --namespace scolah-system
helm uninstall scolah-agent --namespace scolah-system

O Helm deixa duas coisas para trás: as definições de recursos Installation e Link, e o volume de identidade do agente (state-scolah-agent-0). Exclua-os se você não for conectar o cluster novamente.

Recuperação de desastres

Um cluster pode participar da recuperação de desastres dos dois lados. Suas instalações podem ser protegidas e, depois de marcado como elegível para recuperação, ele pode hospedar reservas, para instalações em um servidor Docker ou em outro cluster. Sempre que um cluster estiver envolvido, você precisa de um armazenamento de artefatos que os dois servidores consigam alcançar. Consulte Clusters Kubernetes para saber como funcionam os backups, os testes, o failover e o retorno ao primário em um cluster.

No nível Contínuo, um cluster pode ser o primário ou o servidor de recuperação de bancos de dados PostgreSQL e MariaDB, pareado com um servidor Docker ou com outro cluster. Dos dois lados, você precisa do agente 0.0.2 ou mais recente, de uma StorageClass padrão e da imagem do próprio agente disponível para download: se ela estiver em um registro privado, defina imagePullSecrets no chart do agente, e o agente os copia para o namespace de cada instalação para os pods de recuperação. Como primário, você também precisa de espaço para o volume do expedidor; no PostgreSQL, de uma conta de superusuário do banco de dados, e o agente acrescenta uma linha identificada ao pg_hba.conf sem reiniciar o banco de dados; no MariaDB, do log binário no formato por linha e das permissões de replicação, sem nenhuma alteração no banco de dados. Os dois lados precisam da mesma arquitetura de CPU: em um cluster primário, a plataforma verifica o nó onde roda cada banco de dados, mas em um cluster de recuperação com arquiteturas mistas ela não consegue saber antecipadamente o nó do banco de dados de reserva, então fixe o banco de dados de reserva na arquitetura do primário. Como servidor de recuperação, um banco de dados de reserva PostgreSQL precisa dos dados em um volume que não seja ReadWriteOncePod e é parado brevemente enquanto é preparado a partir de uma base, enquanto um banco de dados de reserva MariaDB continua rodando durante todo o processo. Consulte Nível Contínuo com o primário em um cluster e Nível Contínuo com o servidor de recuperação em um cluster para as listas completas.