Visão geral

O servidor de acesso é um cluster Kubernetes na sua rede. É nele que o PanOps Terminal cria um pod para cada sessão aberta, e é desse pod que sai a conexão com os equipamentos. Recomendamos o K3s: é uma distribuição Kubernetes certificada, instalada com um único comando, e já traz o Metrics Server, que o PanOps usa para mostrar o uso de CPU e memória do servidor.

Este guia instala um K3s de um único servidor, suficiente para a maioria das equipes. No fim, você terá um arquivo kubeconfig para cadastrar no PanOps.

Requisitos

Cada sessão aberta reserva 50m de CPU e 64 MiB de memória e pode usar até 500m e 256 MiB. Um servidor com 2 vCPUs e 4 GB atende algumas dezenas de sessões simultâneas; a tela de Servidores de Acesso mostra a estimativa de quantas ainda cabem.

Regras de rede

Os usuários não acessam o servidor de acesso diretamente: tudo passa pelo PanOps Cloud. Por isso, não é preciso liberar nada da estação dos usuários para o K3s.

Instalando o K3s

Os comandos abaixo são executados como root (ou com sudo) no servidor que será o servidor de acesso.

1. Configuração inicial

Crie o arquivo de configuração antes de instalar. Troque k3s.exemplo.com.br pelo nome DNS ou IP que o PanOps vai usar para chegar até o servidor; ele precisa estar no certificado do K3s.

mkdir -p /etc/rancher/k3s
cat > /etc/rancher/k3s/config.yaml <<'CONF'
# Nome ou IP pelo qual a API do PanOps acessa este servidor.
tls-san:
  - "k3s.exemplo.com.br"
# O Terminal não usa Ingress nem LoadBalancer: dá para desligar e economizar recursos.
disable:
  - traefik
  - servicelb
CONF

2. Firewall do sistema operacional

Se o servidor usa ufw (Ubuntu e Debian), libere a API e as redes internas do K3s. Troque 203.0.113.10 pelo IP da API do PanOps informado pelo suporte (repita a linha para cada IP):

ufw allow from 203.0.113.10 to any port 6443 proto tcp
ufw allow from 10.42.0.0/16 to any   # pods
ufw allow from 10.43.0.0/16 to any   # services

Se usa firewalld (Rocky Linux e RHEL):

firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="203.0.113.10" port port="6443" protocol="tcp" accept'
firewall-cmd --permanent --zone=trusted --add-source=10.42.0.0/16   # pods
firewall-cmd --permanent --zone=trusted --add-source=10.43.0.0/16   # services
firewall-cmd --reload

3. Instalação

curl -sfL https://get.k3s.io | sh -

O script instala a versão estável mais recente do K3s e o deixa como serviço do sistema (k3s). Confira se o nó está pronto e se o Metrics Server responde:

k3s kubectl get nodes
k3s kubectl top nodes

O top nodes pode levar cerca de um minuto para mostrar os números depois da instalação.

Preparando o namespace

As sessões do PanOps rodam sempre no namespace terminal. Crie o namespace, uma conta de serviço para o PanOps e as permissões mínimas. Salve o arquivo abaixo como panops-terminal.yaml:

apiVersion: v1
kind: Namespace
metadata:
  name: terminal
  labels:
    # O pod de sessão atende ao nível mais restrito do Pod Security.
    pod-security.kubernetes.io/enforce: restricted
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: panops-terminal
  namespace: terminal
---
# Permissões que o PanOps precisa no namespace "terminal".
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: panops-terminal
  namespace: terminal
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["create", "get", "list", "delete"]
  - apiGroups: [""]
    resources: ["pods/attach"]
    verbs: ["create", "get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: panops-terminal
  namespace: terminal
subjects:
  - kind: ServiceAccount
    name: panops-terminal
    namespace: terminal
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: panops-terminal
---
# Opcional, somente leitura: deixa o PanOps mostrar o uso de CPU e memória
# e estimar quantas sessões ainda cabem no servidor.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: panops-terminal-monitoring
rules:
  - apiGroups: [""]
    resources: ["nodes", "pods"]
    verbs: ["get", "list"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["nodes", "pods"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: panops-terminal-monitoring
subjects:
  - kind: ServiceAccount
    name: panops-terminal
    namespace: terminal
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: panops-terminal-monitoring
---
# Token de longa duração da conta de serviço, usado no kubeconfig.
apiVersion: v1
kind: Secret
metadata:
  name: panops-terminal-token
  namespace: terminal
  annotations:
    kubernetes.io/service-account.name: panops-terminal
type: kubernetes.io/service-account-token

Aplique o arquivo:

k3s kubectl apply -f panops-terminal.yaml

Gerando o kubeconfig do PanOps

O kubeconfig do PanOps usa o token da conta panops-terminal, e não o arquivo de administrador do K3s (/etc/rancher/k3s/k3s.yaml). Assim o PanOps recebe só as permissões acima.

Troque o endereço em SERVER pelo mesmo nome usado em tls-san e execute:

SERVER="https://k3s.exemplo.com.br:6443"
TOKEN=$(k3s kubectl -n terminal get secret panops-terminal-token -o jsonpath='{.data.token}' | base64 -d)
CA=$(k3s kubectl -n terminal get secret panops-terminal-token -o jsonpath='{.data.ca\.crt}')

cat > panops-terminal.kubeconfig <<CONF
apiVersion: v1
kind: Config
clusters:
  - name: panops-terminal
    cluster:
      server: ${SERVER}
      certificate-authority-data: ${CA}
users:
  - name: panops-terminal
    user:
      token: ${TOKEN}
contexts:
  - name: panops-terminal
    context:
      cluster: panops-terminal
      namespace: terminal
      user: panops-terminal
current-context: panops-terminal
CONF

Teste o arquivo antes de cadastrar. As duas primeiras respostas devem ser yes:

k3s kubectl --kubeconfig panops-terminal.kubeconfig auth can-i create pods -n terminal
k3s kubectl --kubeconfig panops-terminal.kubeconfig auth can-i create pods/attach -n terminal
k3s kubectl --kubeconfig panops-terminal.kubeconfig get pods -n terminal

Com o kubeconfig em mãos, siga para Servidores de Acesso e cadastre o servidor.

Manutenção

Atualizando o K3s

Para atualizar para a versão estável mais recente, execute de novo o script de instalação. Como as opções estão em /etc/rancher/k3s/config.yaml, elas são mantidas:

curl -sfL https://get.k3s.io | sh -

Atualize uma versão menor por vez (por exemplo, de 1.32 para 1.33, e só depois para 1.34). As sessões abertas durante a atualização podem cair.

Trocando o token

Para revogar o acesso do PanOps, apague o secret do token; o kubeconfig antigo deixa de funcionar na hora:

k3s kubectl -n terminal delete secret panops-terminal-token

Para gerar um novo, aplique de novo o panops-terminal.yaml, gere o kubeconfig outra vez e, no PanOps, exclua o servidor de acesso e cadastre-o com o arquivo novo.

Removendo o K3s

/usr/local/bin/k3s-uninstall.sh

O script remove o K3s e todos os dados do cluster.

Outros clusters Kubernetes

O PanOps funciona com qualquer Kubernetes que a API do PanOps consiga alcançar: aplique o mesmo panops-terminal.yaml e gere o kubeconfig da mesma forma (com kubectl no lugar de k3s kubectl). O Metrics Server é opcional; sem ele, as sessões funcionam normalmente, mas o uso de CPU e memória não aparece. Se o seu cluster não tiver o Metrics Server, instale com:

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml