Pular para o conteúdo

Recursos

Terminal de pods

Um usuário cujo papel tem pods.exec abre um shell interativo em um pod pelo Deck. Tudo o que é digitado e tudo o que aparece fica gravado, cada linha de comando vai para a trilha de auditoria, e nada abre sem gravação. As rotas e os formatos estão no CONTRACT.md, Adendo v0.24.

Ligando o terminal

O terminal vem desligado. Duas coisas o ligam, e elas andam juntas:

bash
helm upgrade sreorbit deploy/helm/sreorbit --reuse-values \  --set components.orbit-api.rbac.exec.enabled=true

Isso gera um ClusterRole e um ClusterRoleBinding para o orbit-api com exatamente pods/exec, verbos create e get, e define ORBIT_EXEC_ENABLED como true no ConfigMap dele. O interruptor nunca aparece sem a permissão, nem a permissão sem o interruptor. Ele exige rbac.enabled, como as escritas em workloads, e o chart se recusa a renderizar sem isso.

Depois:

  • components.orbit-api.exec.namespaces (ORBIT_EXEC_NAMESPACES) lista os namespaces onde um terminal pode abrir. Vazia, vale para todo namespace, exceto kube-system. É o padrão: um administrador muda a lista no Deck em Admin → Terminal, e essa escolha vale na hora, sem deploy. Cada mudança entra na auditoria como exec.settings.update, com a lista de antes e a de depois.
  • O namespace do próprio orbit-api é sempre recusado, listado ou não: os pods dele guardam a chave de selagem e todos os bearers.
  • Só o papel embutido admin tem pods.exec. Conceda-o a um papel personalizado em Administração → Papéis.

Abrindo um terminal

A ação Terminal fica na página do pod e em cada linha onde quer que o Deck liste pods, e só aparece quando o seu papel tem pods.exec, o terminal está ligado e o namespace do pod é permitido. Ela abre o xterm.js no pod:

  • o primeiro container por padrão, com um seletor quando o pod tem mais de um;
  • bash quando a imagem o tem, sh caso contrário;
  • um aviso de que a sessão é gravada e auditada;
  • o terminal acompanha o tamanho do painel, e uma conexão que cai reconecta e mostra de novo os últimos 64 KiB de saída;
  • "Encerrar sessão", ou sair da página, fecha o shell;
  • abaixo dele, os logs e os traces do pod na janela de onde você veio, cada um em nova aba para o shell continuar aberto.

A digitação fica à frente da rede. Uma tecla sai na hora, e as teclas digitadas enquanto a requisição dela está em andamento saem juntas na seguinte, até o primeiro Enter, então um link lento custa uma ida e volta por lote, nunca uma fila que cresce. O cabeçalho mostra o tempo de eco, a mediana das suas últimas teclas, do toque ao eco chegar ao terminal, e "sem eco" quando uma tecla ficou 2 segundos sem resposta.

O eco preditivo mostra o que você digita antes de o pod responder, esmaecido e sublinhado até o eco confirmar, como o mosh faz. É uma camada sobre o terminal, então uma previsão nunca entra no buffer do terminal, na requisição ou na gravação. Ele aparece só depois que uma tecla ecoou onde foi digitada e a partir de 30 ms de ida e volta, e uma saída que move o cursor encerra isso, então um novo prompt começa sem previsão. Nunca aparece em um prompt de segredo, em um programa de tela cheia, sobre texto à direita do cursor, ou depois de um eco que difere ou não vem. Só caracteres comuns são previstos. Enter, Tab, uma seta ou qualquer outra tecla de controle deixa no lugar o que já foi desenhado até o eco chegar, e as teclas seguintes esperam o delas; o Backspace também retira a última tecla ainda não confirmada. Um programa que desliga o eco sem imprimir nada ainda pode mostrar suas teclas até o eco que falta expirar, em 2 segundos. Para desligar, use o cabeçalho; o navegador lembra.

Ctrl+Shift+F busca no histórico: Enter vai para um resultado mais antigo, Shift+Enter para um mais recente, Esc fecha. Ctrl+C copia quando há texto selecionado e é a interrupção caso contrário; no Mac, Cmd+C copia e Ctrl+C é sempre a interrupção. Ctrl+Shift+V cola, e o Ctrl+V também em uma linha do shell; um programa de tela cheia, como o vim, recebe o Ctrl+V, e no Mac o Cmd+V cola. Um endereço web na saída abre com um clique, depois de ser mostrado a você.

Uma recusa diz o motivo: o terminal está desligado, o namespace não é permitido, você já tem 4 sessões abertas, o orbit-api tem 16, ou esta é a demonstração pública. Cada recusa também fica na auditoria.

Limites

LimitePadrãoConfiguração
Inatividade, sem digitação15 minutosORBIT_EXEC_IDLE_TIMEOUT_S
Sessão mais longa2 horasORBIT_EXEC_MAX_DURATION_S
Saída gravada por sessão64 MiBfixo
Gravações guardadas90 diasORBIT_EXEC_RETENTION_DAYS
Gravações no total512 MiBORBIT_EXEC_RECORDINGS_MAX_BYTES
Sessões abertas4 por usuário, 16 no totalfixo

Uma sessão que passa de um limite termina com o motivo idle, max_duration ou recording_limit. Desligar o terminal em Admin → Recursos encerra toda sessão aberta em até um segundo, com o motivo feature_disabled. As gravações mais antigas saem primeiro, quando uma sessão começa e uma vez por hora. Nenhuma rota exclui uma gravação.

Quando digitar parece lento

Uma tecla sai do navegador, passa por uma eventual CDN e pelo ingress até o web, o orbit-api e o pod, e o eco volta pelo mesmo caminho. O web e o orbit-api ficam com poucos milissegundos disso. O resto é o seu link e o caminho do próprio cluster até o pod, pelo API server e pelo kubelet.

Para ler essa divisão na sua instalação, abra as ferramentas de desenvolvedor do navegador, escolha uma chamada input na aba Network e abra Timing. web, em Server Timing, é quanto o web esperou o orbit-api aceitar a tecla; o orbit-api responde assim que a tecla entra na fila, então isso não cobre o pod nem o eco. O total menos esse valor é o seu link, a eventual CDN, o ingress e poucos milissegundos do próprio web. pod é a viagem da primeira tecla depois de uma pausa do orbit-api até o pod e de volta, pelo API server e pelo kubelet, então uma rajada de digitação mantém essa leitura. Qualquer saída conta como resposta: o valor fica baixo enquanto um programa imprime sem parar e até 2 segundos acima do real depois de uma tecla que o programa não ecoa. Passando de 2 segundos, pod não aparece, então digitar sem pod significa falta de eco ou um cluster lento assim.

As teclas chegam na hora a um programa que inunda o terminal, então o Ctrl-C o interrompe, e uma colagem longa também passa. A tela demora mais: até 8 MiB de saída já a caminho do navegador, mais o que os sockets no caminho guardam, ainda chegam depois do Ctrl-C. Um navegador mais atrasado que isso é desconectado e reconecta aos últimos 64 KiB.

O que fica gravado

Cada sessão é um arquivo asciicast v2 no diretório de dados do orbit-api, exec/<id>.cast: um cabeçalho com o tamanho, o início e o título (usuário, namespace, pod e container), e depois cada trecho de saída, cada tecla e cada redimensionamento, com o seu tempo. O cabeçalho é gravado antes que o primeiro byte chegue ao navegador; se não puder ser gravado, a sessão é recusada. Os eventos vão para o disco pelo menos a cada segundo, e uma escrita que falha encerra a sessão com recording_failed: nada roda sem gravação.

A trilha de auditoria recebe três tipos de evento, com o usuário como autor e o alvo pod <namespace>/<pod>:

AçãoQuandoDetalhes
pod.exec.startUma sessão abre ou é recusadacluster, container, session, o motivo e o endereço do cliente
pod.exec.commandCada linha de comando, no máximo 1.000 por sessãoline (o primeiro 1 KiB), t e approximate
pod.exec.endUma sessão terminadurationMs, exitCode, reason, inputBytes, outputBytes e commands

As linhas de comando são lidas das teclas por um pequeno editor de linha: digitar acrescenta, Backspace apaga, Ctrl-U limpa a linha, Ctrl-C a descarta e Enter a termina. Uma linha editada com as setas, o histórico ou Tab é marcada como aproximada, porque o shell pode ter rodado outra coisa. A gravação, e não a lista de linhas, é a fonte da verdade.

Duas coisas ficam fora de ambas. Quando a saída do pod termina num pedido de senha, frase secreta, PIN, segredo ou token ([sudo] password for dev:, Enter passphrase for key), as teclas até o próximo Enter são gravadas como um * cada; o shell não as ecoa, então a saída também não as guarda. Os formatos de credencial numa linha de comando (--password=x, --token x, password=x, PGPASSWORD=x, mysql -px, sshpass -p x, curl -u user:x, redis-cli -a x, Bearer x, user:pass@ numa URL, chaves privadas, chaves de nuvem e do GitHub) aparecem como [redacted] em pod.exec.command, na lista de comandos da sessão e no comando inicial que pod.exec.start e a lista de sessões mostram, inclusive as de sessões antigas; o pod continua rodando o comando como foi enviado. O orbit-api também as troca por estrelas na gravação, um * por caractere, nas teclas e no eco do shell: ele segura a linha e a saída dela na memória até passar um segundo depois do Enter e só então grava as duas. Ele também remonta cada linha da saída como o terminal a desenha e troca os mesmos formatos por estrelas ali, então uma credencial digitada numa sessão anterior e mostrada de novo nesta (history, a seta para cima, Ctrl-R, env, ps) chega à gravação como estrelas. Uma credencial de 4 caracteres ou mais continua coberta por estrelas na saída seguinte da mesma sessão. GET /api/v1/exec/sessions/{id}/cast aplica o mesmo tratamento, antes de entregá-la, a uma gravação feita por uma versão anterior. Restam três limites. O orbit-api casa cada caractere ecoado com a tecla que o digitou, em ordem, então a saída que um programa imprime enquanto você digita pode desfazer um par e deixar parte do eco legível. Uma linha que continua aberta depois de 30 segundos ou 256 KiB chega à gravação com estrelas só onde já mostra um formato de credencial. Quando o pod manda uma linha em duas leituras, uma credencial reconhecida só pelo que vem depois dela (user:pass@, Bearer x) deixa legível a parte que a primeira leitura trouxe. Digite segredos num prompt ou leia-os de um arquivo.

Revendo uma sessão

Administração → Trilha de auditoria → Sessões de terminal (/deck/admin/audit/sessions, sob audit.read) lista cada sessão, da mais recente para a mais antiga, com filtros por usuário, namespace e pod. A página de uma sessão mostra quem a abriu, de onde, quando, por quanto tempo e como terminou, e reproduz a gravação com o tempo dela. A gravação chega aos poucos, então os controles funcionam na hora sobre o que já chegou, seja qual for o tamanho, e a tela abre na última da sessão assim que o navegador termina de ler.

  • Reproduzir e posicionar. Reproduzir e pausar, de 1× a 8×, e um controle deslizante. Mudar de posição escreve o quadro-chave mais próximo e o que vem depois dele, nunca a gravação desde o zero, então custa o mesmo em qualquer ponto da gravação, por mais longa que seja. Rolar para cima depois disso mostra o que veio logo antes, não a sessão inteira.
  • Linha do tempo. Uma marca por linha de comando e uma faixa por silêncio longo; um clique na marca vai até ela.
  • Silêncios. "Pular silêncios", ligado por padrão, toca cada silêncio até 2 segundos. O relógio continua mostrando o tempo real.
  • Busca. No que a sessão imprimiu, sem as cores e onde quer que a saída tenha sido cortada: cada ocorrência diz quando apareceu, e um clique vai até aquele momento, com a tela rolada até o trecho e o trecho destacado. As teclas digitadas não entram na busca, só o que a tela mostrou. Credenciais mascaradas não estão na gravação, então nem a busca nem uma mudança de posição as trazem de volta.
  • Link para um momento. "Copiar link deste momento" dá o endereço da página com #t=<seconds> (em segundos). Ele abre naquele momento para quem tem audit.read, passando pelo login se for preciso. Onde o navegador recusa a área de transferência, a página avisa que o link está na barra de endereço. A busca nunca entra no link.
  • Teclas. Espaço ou K reproduzem e pausam, ← → andam 5 s (30 s com Shift), Home e End, N e P o próximo comando e o anterior, < e > a velocidade, I os silêncios, / a busca. Elas respondem enquanto o foco está no player, onde a página o coloca ao abrir; com o foco em outro lugar, essas teclas ficam com a página.

As linhas de comando aparecem com os seus tempos; um clique reproduz a gravação a partir daquela linha. "Baixar gravação" salva o arquivo .cast, que qualquer player de asciicast também reproduz.

Pela API

RotaRequerCorpo e resposta
GET /api/v1/exec/statuspods.exec{enabled, namespaces, idleTimeoutS, maxDurationS, reason}
POST /api/v1/clusters/{id}/pods/{namespace}/{pod}/execpods.exec{container, command, cols, rows} → 201 com a sessão
GET /api/v1/exec/{id}/streamO próprio usuário da sessãoServer-sent events
POST /api/v1/exec/{id}/inputO mesmo{data}, em base64, no máximo 64 KiB → 204
POST /api/v1/exec/{id}/resizeO mesmo{cols, rows} → 204
DELETE /api/v1/exec/{id}O mesmo204, encerra a sessão
GET /api/v1/exec/sessionsaudit.read{sessions, next}, da mais recente para a mais antiga
GET /api/v1/exec/sessions/{id}audit.readA sessão e as suas lines
GET /api/v1/exec/sessions/{id}/castaudit.readA gravação, application/x-asciicast

O stream envia eventos output (base64 dos bytes brutos), um evento exit com o código e o motivo, e um comentário : ping a cada 15 s. Uma segunda leitura do stream substitui a primeira e começa pelos últimos 64 KiB de saída. Qualquer um que não seja o próprio usuário da sessão recebe 404.

O servidor web repassa as chamadas de digitação, de tamanho e de encerramento, e a abertura, só na sessão do usuário que entrou, nunca com um token de operador, e só a partir das páginas do próprio console.