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:
helm upgrade sreorbit deploy/helm/sreorbit --reuse-values \ --set components.orbit-api.rbac.exec.enabled=trueIsso 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, excetokube-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 comoexec.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
admintempods.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;
bashquando a imagem o tem,shcaso 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
| Limite | Padrão | Configuração |
|---|---|---|
| Inatividade, sem digitação | 15 minutos | ORBIT_EXEC_IDLE_TIMEOUT_S |
| Sessão mais longa | 2 horas | ORBIT_EXEC_MAX_DURATION_S |
| Saída gravada por sessão | 64 MiB | fixo |
| Gravações guardadas | 90 dias | ORBIT_EXEC_RETENTION_DAYS |
| Gravações no total | 512 MiB | ORBIT_EXEC_RECORDINGS_MAX_BYTES |
| Sessões abertas | 4 por usuário, 16 no total | fixo |
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ção | Quando | Detalhes |
|---|---|---|
pod.exec.start | Uma sessão abre ou é recusada | cluster, container, session, o motivo e o endereço do cliente |
pod.exec.command | Cada linha de comando, no máximo 1.000 por sessão | line (o primeiro 1 KiB), t e approximate |
pod.exec.end | Uma sessão termina | durationMs, 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 temaudit.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
| Rota | Requer | Corpo e resposta |
|---|---|---|
GET /api/v1/exec/status | pods.exec | {enabled, namespaces, idleTimeoutS, maxDurationS, reason} |
POST /api/v1/clusters/{id}/pods/{namespace}/{pod}/exec | pods.exec | {container, command, cols, rows} → 201 com a sessão |
GET /api/v1/exec/{id}/stream | O próprio usuário da sessão | Server-sent events |
POST /api/v1/exec/{id}/input | O mesmo | {data}, em base64, no máximo 64 KiB → 204 |
POST /api/v1/exec/{id}/resize | O mesmo | {cols, rows} → 204 |
DELETE /api/v1/exec/{id} | O mesmo | 204, encerra a sessão |
GET /api/v1/exec/sessions | audit.read | {sessions, next}, da mais recente para a mais antiga |
GET /api/v1/exec/sessions/{id} | audit.read | A sessão e as suas lines |
GET /api/v1/exec/sessions/{id}/cast | audit.read | A 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.