Instalação
Helm
O caminho de produção, para qualquer cluster real. Esta página foi validada contra o chart
atual: deploy/helm/sreorbit implementa o desenho completo do Adendo v0.2 (autenticação,
isolamento de métricas, roteamento por um único ingress, travamento por digest), e todo
comando abaixo foi executado contra o chart deste repositório enquanto esta página era
escrita.
Pré-requisitos
| Requisito | Versão | Por quê |
|---|---|---|
| Kubernetes | 1.30+ | preStopSleepSeconds (no web por padrão, para um drain de nó não cortar uma resposta do Nocturne; em todos os componentes no values-prod.yaml) precisa de PodLifecycleSleepAction, estável desde a 1.30. |
| Helm | 3.x (validado com 3.16.4) | A validação por values.schema.json e o comportamento de --dry-run=server pressupõem o Helm 3. |
kubectl | compatível com a versão minor do seu cluster | Os comandos de verificação e de acompanhamento de rollout abaixo. |
| Um ingress controller | o values-prod.yaml pressupõe nginx (ingress.className: nginx); o chart renderiza automaticamente anotações seguras para SSE para essa classe | Defina ingress.className de acordo com o controller que você usa; veja troubleshooting.md se o streaming parecer ter buffer. |
docker buildx (ou crane) | vem com o Docker moderno | Resolver os digests das imagens antes de uma instalação de produção; veja abaixo. |
| Imagens publicadas em um registry que você controla | n/a | O values-prod.yaml se recusa a renderizar sem digests, e um digest só pode ser resolvido depois que a imagem existe em um registry. Esta página pressupõe que o ghcr.io/sreorbit/* (ou o registry do seu fork) já tem a tag que você vai instalar. |
Confirme o que você tem:
kubectl version --clienthelm versionAntes da sua primeira instalação em produção
Quatro coisas, nesta ordem, tiradas do próprio cabeçalho do values-prod.yaml:
- Aponte
ingress.hostpara um nome DNS real que você controla. - Crie o secret de TLS (ou deixe o cert-manager criá-lo pela anotação
cert-manager.io/cluster-issuer) e defina o nome dele. - Crie o Secret de credenciais fora do chart (abaixo) e defina
secrets.existingSecret. - Resolva a imagem de cada componente para um digest (abaixo).
E duas que o Adendo v0.5 acrescenta: nomeie uma StorageClass para o volume do orbit-api
(components.orbit-api.persistence.storageClassName, um CHANGEME no values-prod.yaml)
e decida como o primeiro administrador vai passar a existir ("O primeiro administrador"
abaixo).
Cada valor, em um só lugar
A tabela completa de variáveis de ambiente (defaults e significados) está em
../configuration.md; cada uma delas mapeia para
components.<name>.env.<VAR> ou components.<name>.secretEnv.<VAR> no values.yaml.
Portas: web 3000, orbit-api 8080+9090, nocturne 8081+9090, orbit-stack
8082+9090, fixas e não configuráveis por values. O values.schema.json rejeita uma chave desconhecida ou um caminho
digitado errado no momento da instalação (additionalProperties: false em toda parte), em
vez de deixá-lo passar silenciosamente sem efeito por um rollout.
Gere os seus tokens
ORBIT_AUTH_TOKEN=$(openssl rand -hex 32)NOCTURNE_AUTH_TOKEN=$(openssl rand -hex 32)ORBIT_STACK_AUTH_TOKEN=$(openssl rand -hex 32)Crie o Secret de credenciais
O chart nunca entrega um valor: "Secrets are referenced, never embedded in a chart default"
(Secrets são referenciados, nunca embutidos em um default de chart). Crie o Secret você mesmo, com estas quatro chaves (um
NOCTURNE_API_KEY vazio é válido: é do que o NOCTURNE_PROVIDER=mock precisa; as chaves
opcionais aparecem mais adiante nesta página):
kubectl create namespace sreorbit --dry-run=client -o yaml | kubectl apply -f - kubectl -n sreorbit create secret generic sreorbit-secrets \ --from-literal=ORBIT_AUTH_TOKEN="$ORBIT_AUTH_TOKEN" \ --from-literal=NOCTURNE_AUTH_TOKEN="$NOCTURNE_AUTH_TOKEN" \ --from-literal=ORBIT_STACK_AUTH_TOKEN="$ORBIT_STACK_AUTH_TOKEN" \ --from-literal=NOCTURNE_API_KEY=""(O chart renderiza o próprio namespace, com os labels de Pod Security Admission, mas o Helm precisa que o namespace exista antes de renderizar qualquer coisa e só adota um objeto que carregue os metadados de propriedade dele. Crie-o uma vez, marcado como pertencente à release, antes de o Secret entrar:
kubectl create namespace sreorbitkubectl label namespace sreorbit app.kubernetes.io/managed-by=Helmkubectl annotate namespace sreorbit \ meta.helm.sh/release-name=sreorbit meta.helm.sh/release-namespace=sreorbitO helm upgrade --install então aplica os labels de PSA a partir do template em toda
instalação e atualização. Um namespace criado de forma simples, ou por
--create-namespace, faz o Helm recusar com "exists and cannot be imported into the current
release".)
Para um provedor real em vez do mock, coloque um valor real em NOCTURNE_API_KEY e defina
components.nocturne.env.NOCTURNE_PROVIDER e
components.nocturne.networkPolicy.allowInternetEgress: true no momento da instalação (veja
"Instale" abaixo). As duas opções são obrigatórias juntas; nenhuma implica a outra.
Prefira External Secrets, Sealed Secrets ou SOPS a um kubectl create secret rodado à mão
para qualquer coisa que você vá operar por muito tempo. O secrets.existingSecret (usado
abaixo) funciona do mesmo jeito com qualquer um deles, já que o chart apenas referencia o
Secret pelo nome.
O próprio login do web
O web autentica com HTTP Basic cada requisição que atende: páginas, o Deck, toda chamada
/api/*, incluindo os streams de SSE, e os arquivos estáticos. Só o GET /healthz fica
isento: o proxy responde a ele sozinho, 200 {"status":"ok"}, antes de a autenticação ou
o roteamento de idioma rodarem. Sem isso, qualquer pod que consiga alcançar
<release>-web:3000 diretamente (algo rotineiro onde a CNI não impõe NetworkPolicy)
conseguiria ler logs, ConfigMaps, literais de env, eventos, inventário e PromQL sem
credencial; o basic auth no nível do ingress, sozinho, nunca cobriu
esse caminho. Veja security.md para o modelo de ameaça completo.
components.web.auth.enabled liga isso; o default agora é true com o
ingress.enabled ligado ou desligado, já que um pod consegue alcançar o web
diretamente sem passar pelo ingress. Defina-o como false você mesmo para
desativar.
Gere uma senha e faça o hash dela; o chart e o próprio web só enxergam o hash:
openssl rand -base64 24 > web-password && chmod 600 web-passwordWEB_AUTH_VERIFIER="$(node apps/web/scripts/hash-password.mjs < web-password)"O hash-password.mjs lê a senha só via stdin, nunca como argumento de linha de comando;
recusa um terminal interativo; remove uma quebra de linha final; e recusa qualquer coisa
com menos de 15 caracteres. Ele imprime um verificador PBKDF2, nunca a própria senha:
pbkdf2-sha256$<iterations>$<base64 salt>$<base64 hash>, PBKDF2-HMAC-SHA256 com um salt
aleatório de 16 bytes e um hash de 32 bytes, nas 600.000 iterações que o script grava (o
formato do verificador aceita qualquer valor a partir de 210.000).
Acrescente WEB_AUTH_USER e WEB_AUTH_VERIFIER ao Secret, junto com as quatro chaves
acima:
kubectl -n sreorbit create secret generic sreorbit-secrets \ --from-literal=ORBIT_AUTH_TOKEN="$ORBIT_AUTH_TOKEN" \ --from-literal=NOCTURNE_AUTH_TOKEN="$NOCTURNE_AUTH_TOKEN" \ --from-literal=ORBIT_STACK_AUTH_TOKEN="$ORBIT_STACK_AUTH_TOKEN" \ --from-literal=NOCTURNE_API_KEY="" \ --from-literal=WEB_AUTH_USER="admin" \ --from-literal=WEB_AUTH_VERIFIER="$WEB_AUTH_VERIFIER"As duas chaves chegam ao contêiner por secretKeyRef sem optional: true, então a
falta de uma delas vira CreateContainerConfigError, não um bypass silencioso, e o pod
sobe sozinho assim que as duas chaves existirem. Com o Secret criado pelo chart em vez de
secrets.existingSecret, defina secrets.webAuthUser e
secrets.webAuthVerifier, e o chart escreve as chaves para você (ele só as renderiza
quando definidas, então chaves que você acrescentou depois à mão sobrevivem ao próximo
helm upgrade); o values.schema.json rejeita um secrets.webAuthVerifier que não
esteja no formato de verificador acima. As duas ficam ignoradas, porém,
quando a release não cria o Secret (secrets.existingSecret definido, ou
secrets.create=false); o NOTES.txt avisa disso nesse caso.
ingress.basicAuth.enabled e components.web.auth.enabled não podem estar ligados ao
mesmo tempo; "Amazon EKS" abaixo explica por que o chart se recusa a renderizar essa
combinação.
Ativando isso em uma instalação que já está rodando: acrescente as chaves antes de ativar a opção, para que o rollout que liga a autenticação nunca chegue a um pod sem elas:
VERIFIER="$(node apps/web/scripts/hash-password.mjs < /path/to/web-password)"kubectl -n sreorbit patch secret sreorbit-secrets --type merge --dry-run=server \ -p "{\"stringData\":{\"WEB_AUTH_USER\":\"admin\",\"WEB_AUTH_VERIFIER\":\"$VERIFIER\"}}"kubectl -n sreorbit patch secret sreorbit-secrets --type merge \ -p "{\"stringData\":{\"WEB_AUTH_USER\":\"admin\",\"WEB_AUTH_VERIFIER\":\"$VERIFIER\"}}"unset VERIFIERhelm upgrade sreorbit deploy/helm/sreorbit -n sreorbit --reuse-values \ --set components.web.auth.enabled=true --set ingress.basicAuth.enabled=falseAs sondas de startup, liveness e readiness do web foram todas movidas para
GET /healthz (saindo de /, que agora exige a credencial). Um curl simples ali,
sem -u, ainda distingue o caminho da sonda de tudo o mais.
O Basic auth do web protege o site inteiro. A próxima seção trata de quem uma pessoa é
dentro do console e do que ela pode fazer lá.
O primeiro administrador, e o volume do orbit-api
Toda página do Deck exige um usuário logado, e o orbit-api cria o primeiro na primeira
inicialização (../identity.md → "O primeiro administrador"). Em
produção, entregue esse administrador pelo Secret, antes da instalação:
openssl rand -base64 24 > admin-password && chmod 600 admin-passwordVERIFIER="$(node apps/web/scripts/hash-password.mjs < admin-password)"kubectl -n sreorbit patch secret sreorbit-secrets --type merge \ -p "{\"stringData\":{\"ORBIT_ADMIN_USER\":\"admin\",\"ORBIT_ADMIN_PASSWORD_VERIFIER\":\"$VERIFIER\",\"ORBIT_SESSION_SECRET\":\"$(openssl rand -base64 48 | tr -d '\n')\"}}"unset VERIFIERAs três chaves são opcionais (secretKeyRef com optional: true) e são lidas uma única
vez, quando o contêiner sobe:
ORBIT_ADMIN_USEReORBIT_ADMIN_PASSWORD_VERIFIERcriam esse administrador só enquanto não existe nenhum usuário, e depois disso são ignoradas. Sem as duas, oorbit-apiregistra no log um código de configuração de uso único:kubectl -n sreorbit logs deploy/sreorbit-orbit-api | grep setup_code; em seguida, abrahttps://YOUR_REAL_HOSTNAME/login.ORBIT_SESSION_SECRETassina os tokens de sessão; sem ela, uma chave é gerada dentro do diretório de dados. Defini-la mantém a chave fora do volume e dos backups dele.
Com o Secret criado pelo chart em vez de secrets.existingSecret, as mesmas três viram
secrets.adminUser, secrets.adminPasswordVerifier e secrets.sessionSecret,
renderizadas apenas quando definidas.
Usuários, papéis, sessões, dashboards salvos e a trilha de auditoria ficam em
ORBIT_DATA_DIR (/var/lib/sreorbit). O components.orbit-api.persistence coloca esse
diretório em um claim ReadWriteOnce, <release>-orbit-api-data, que sobrevive à
desinstalação como o do engine; desligado (o default no values.yaml), ele vira um
emptyDir dimensionado por emptyDirSizeLimit (256Mi), e tudo o que houver nele some
junto com o pod. O values-prod.yaml o liga com 1Gi e uma storageClassName que você
precisa nomear, e o values-eks.yaml cria para ele uma classe gp3 criptografada, como faz
para o engine. As chaves de armazenamento são as mesmas do engine: veja "O volume do engine"
abaixo. Como o armazenamento tem um único escritor, o chart roda o orbit-api com uma só
réplica, diga o replicaCount o que disser, com rollout Recreate quando a persistência
está ligada e sem PodDisruptionBudget, e se recusa a renderizar com
components.orbit-api.autoscaling.enabled. Faça backup do claim: ../operations.md.
Resolva os digests das imagens
O values-prod.yaml define requireDigest: true: o chart se recusa a renderizar se o
image.digest de qualquer componente habilitado estiver vazio, e nomeia a correção exata na
própria mensagem de erro. Resolva um digest por componente, e um por engine orbit-* que os
values padrão rodam:
for c in web orbit-api nocturne orbit-stack; do echo "$c: $(docker buildx imagetools inspect ghcr.io/sreorbit/$c:0.1.0 | awk '/^Digest:/{print $2}')"doneREPO=ghcr.io/sreorbitfor e in orbit-agent orbit-node orbit-state orbit-collector; do echo "$e: $(docker buildx imagetools inspect $REPO/$e:0.1.0 | awk '/^Digest:/{print $2}')"done(crane digest ghcr.io/sreorbit/$c:0.1.0 é o one-liner equivalente se você tiver o crane
instalado; as duas ferramentas resolvem o mesmo digest, já que ele pertence à imagem, não à
ferramenta que a lê.)
Coloque os oito resultados em um arquivo (um engine trocado pela imagem upstream deixa de ler
o seu digest orbit, e o do apm.collector só é lido quando o coletor está habilitado):
cat > digests.yaml <<'EOF'components: web: image: digest: sha256:PASTE_THE_WEB_DIGEST_HERE orbit-api: image: digest: sha256:PASTE_THE_ORBIT_API_DIGEST_HERE nocturne: image: digest: sha256:PASTE_THE_NOCTURNE_DIGEST_HERE orbit-stack: image: digest: sha256:PASTE_THE_ORBIT_STACK_DIGEST_HEREtelemetry: agent: orbit: image: digest: sha256:PASTE_THE_ORBIT_AGENT_DIGEST_HERE nodeExporter: orbit: image: digest: sha256:PASTE_THE_ORBIT_NODE_DIGEST_HERE kubeStateMetrics: orbit: image: digest: sha256:PASTE_THE_ORBIT_STATE_DIGEST_HEREapm: collector: orbit: image: digest: sha256:PASTE_THE_ORBIT_COLLECTOR_DIGEST_HEREEOF(deploy/helm/sreorbit/digests.example.yaml é o mesmo arquivo, versionado apenas como
referência de sintaxe: os digests dele são sha256:0000...0000 e não resolvem para nada,
então não instale com ele como está.)
Pré-visualize antes de instalar
helm lint deploy/helm/sreorbit -f deploy/helm/sreorbit/values-prod.yaml -f digests.yamlhelm template sreorbit deploy/helm/sreorbit -n sreorbit \ -f deploy/helm/sreorbit/values-prod.yaml -f digests.yaml \ --set ingress.host=YOUR_REAL_HOSTNAME \ --set secrets.existingSecret=sreorbit-secrets \ --set secrets.create=false \ | lessLeia a saída e confirme: exatamente uma regra de Ingress (apenas o web; um segundo bloco
path: roteando para o orbit-api significa que o seu overlay de values está errado), todo
contêiner com requests e limits, e toda referência de imagem
terminando em @sha256:..., não em :0.1.0.
Instale
helm upgrade --install sreorbit deploy/helm/sreorbit \ --namespace sreorbit \ -f deploy/helm/sreorbit/values-prod.yaml -f digests.yaml \ --set ingress.host=YOUR_REAL_HOSTNAME \ --set ingress.tls.secretName=YOUR_TLS_SECRET_NAME \ --set secrets.existingSecret=sreorbit-secrets \ --set secrets.create=false \ --timeout 5m --waitSem --create-namespace: namespace.create: true (o default) renderiza o próprio
Namespace, carregando os labels de Pod Security Admission, e adota o que você marcou acima. O
--create-namespace criaria primeiro um namespace sem marcação, e o Helm então se recusaria
a adotá-lo. Se o namespace é gerenciado em outro lugar, defina namespace.create=false e
aplique você mesmo o label pod-security.kubernetes.io/enforce: restricted.
Como é uma instalação saudável
kubectl -n sreorbit rollout status deploy/sreorbit-web --timeout=180skubectl -n sreorbit rollout status deploy/sreorbit-orbit-api --timeout=180skubectl -n sreorbit rollout status deploy/sreorbit-nocturne --timeout=180skubectl -n sreorbit get pods,svc,ingress -l app.kubernetes.io/instance=sreorbitTodo pod em Running e Ready; o Ingress mostrando o seu hostname com exatamente um
endereço; a saída do próprio NOTES.txt do helm install (impressa automaticamente, ou
reexibida com helm -n sreorbit get notes sreorbit) listando cada componente habilitado com
a referência de imagem resolvida e a contagem de réplicas, e imprimindo um WARNING se algum
componente ficar sem limites de recurso, o que não deveria acontecer.
Verifique
kubectl -n sreorbit port-forward svc/sreorbit-orbit-api 8080:8080 &curl -fsS localhost:8080/healthzcurl -fsS localhost:8080/readyzcurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" localhost:8080/api/v1/auth/statekill %1 # stop the port-forwardA última chamada prova que o bearer está certo (401 caso contrário) e diz se o primeiro
administrador já existe: "setupRequired":false depois que o administrador do Secret foi
criado, true enquanto o orbit-api espera o código de configuração. Todas as outras rotas
também exigem uma sessão; ../identity.md → "Entrar pelo shell" mostra
como obter uma.
Depois, no navegador: https://YOUR_REAL_HOSTNAME/. O site institucional renderiza assim
que você responder ao prompt de Basic auth do próprio navegador com o par usuário/senha de
WEB_AUTH_USER definido acima, e o /deck manda você para /login, onde o administrador
faz login. Se ORBIT_DEMO_DATA for false (o default do values-prod.yaml) e você ainda
não tiver montado um kubeconfig, o orbit-api reporta NotReady, que é o sinal
correto e não um bug; veja troubleshooting.md.
Telemetria
O bloco telemetry do values.yaml vem ligado por padrão e não depende de nada que já
exista no cluster: nada de Prometheus, kube-state-metrics, node-exporter, CRD
ServiceMonitor ou namespace de monitoramento. São quatro chaves independentes:
telemetry.enabled, telemetry.agent.enabled, telemetry.kubeStateMetrics.enabled,
telemetry.nodeExporter.enabled.
| Componente | Padrão (orbit) | Upstream, ainda selecionável | O que faz |
|---|---|---|---|
| Agente de scrape | orbit-agent | quay.io/prometheus/prometheus:v3.15.1 (telemetry.agent.engine: prometheus) | Faz scrape do cluster e remote-write para o orbit-stack. Mais ninguém o lê. |
| kube-state-metrics | orbit-state | registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.20.0 (telemetry.kubeStateMetrics.engine: upstream) | Contagens e estados dos objetos: deployments, pods, capacidade dos nodes. |
| node-exporter | orbit-node | quay.io/prometheus/node-exporter:v1.12.1 (telemetry.nodeExporter.engine: upstream) | CPU, memória, disco e rede de cada node; um pod de DaemonSet por node. |
Os engines padrão são os em Rust, de services/rust/: imagens do produto sob o
image.registry, travadas por digest em produção como qualquer componente
(telemetry.<part>.orbit.image). Eles mantêm os Services, jobs, labels, RBAC e
NetworkPolicies dos upstream, então trocar de engine é um único rolling update e nenhum
painel muda. As imagens upstream são multi-arquitetura (amd64 e arm64, então nodes Graviton
funcionam) e travadas por digest além da tag, cada uma com seu próprio
telemetry.<part>.image.registry para um mirror privado (um pull-through cache do ECR
preserva o digest; um mirror que republica a imagem não preserva).
O agente só faz scrape e remote-write, sem API de consulta própria,
como um Deployment de réplica única com estratégia Recreate (um pod extra durante o
rollout escreveria a mesma série duas vezes, com timestamps diferentes). O WAL dele mora
em um emptyDir dimensionado por telemetry.agent.walSizeLimit (padrão 1Gi); se o
orbit-stack ficar inacessível, o orbit-agent guarda no máximo 2h e 90% desse limite,
descartando primeiro o mais antigo, e o Prometheus descarta amostras com mais de 4h, em
vez de deixar o WAL crescer sem limite. Ele faz remote-write para
http://<release>-orbit-stack.<namespace>.svc.cluster.local:8082/api/v1/write,
apresentando o ORBIT_STACK_AUTH_TOKEN como arquivo montado quando a autenticação do
orbit-stack é estática, e carimba cada série com cluster=<telemetry.clusterName>; um valor
vazio cai para components.orbit-api.env.ORBIT_CLUSTER_ID e, por fim, para o nome da release.
O orbit-agent envia só o que o produto lê. Ele descarta as famílias do seu DEFAULT_DROP
(services/rust/orbit-agent/src/config.rs) e os cgroups do cAdvisor que não são um
contêiner: o de um pod, o do sandbox dele, o de um system slice. Os contadores de rede de cada
pod e o cgroup raiz do node ficam. Um pod passa a custar cerca de 65 séries em vez de 170.
telemetry.agent.orbit.keepAllSeries: true envia tudo.
O orbit-state e o orbit-node nem renderizam as famílias descartadas que ninguém lê:
kube_replicaset_* (o orbit-state então não observa ReplicaSets), kube_*_annotations,
kube_pod_tolerations e node_ipvs_*. Elas voltam com keepAllSeries, com
telemetry.agent.engine: prometheus ou com telemetry.agent.enabled: false, quando outra coisa
pode lê-las: o chart então define ORBIT_STATE_UNREAD_FAMILIES e
ORBIT_NODE_UNREAD_FAMILIES como true.
Os jobs de scrape, com nomes exatos que o orbit-api e o Deck consultam (renomear um deles esvazia um painel):
| Job | Alvo |
|---|---|
kubelet | InternalIP:10250 de cada node, com o token da própria ServiceAccount do agente; só com engine: prometheus, já que nada o consulta |
cadvisor | O mesmo host, em /metrics/cadvisor |
kube-state-metrics | Descoberta por EndpointSlice no namespace da release |
node-exporter | Descoberta de pods em <release>-node |
sreorbit | As próprias portas :9090 da release (orbit-api, nocturne, orbit-stack) |
kube-state-metrics e node-exporter ficam de fora do job sreorbit para nada ser raspado
duas vezes. Nodes Fargate são ignorados pelos jobs kubelet e cadvisor: um kubelet no
Fargate só responde por nodes/proxy, permissão que este chart nunca concede.
TLS nos jobs kubelet/cadvisor: telemetry.agent.kubeletInsecureSkipVerify agora vem
false por padrão: o agente valida o certificado de serviço do kubelet contra a CA do
cluster, o mesmo que nodes padrão da EKS (AL2023, Bottlerocket) e o k3s já fazem. Só marque
true para imagens de node que apresentem um certificado de kubelet autoassinado (padrão
do kubeadm, algumas AMIs customizadas); o sintoma nesse caso são os alvos kubelet e
cadvisor caídos com erro de x509.
O RBAC é bem restrito: um ClusterRole recebe apenas nodes/metrics (get) e nodes
(list/watch); Roles namespaced acrescentam list/watch em pods, services e
endpointslices no namespace da release, e em pods em <release>-node. O chart
nunca concede nodes/proxy, que alcançaria qualquer endpoint de kubelet, exec incluído,
através da API server. O ClusterRole do kube-state-metrics é o conjunto padrão sem Secrets (o
coletor de Secrets vem desligado), sem tokenreviews nem subjectaccessreviews.
telemetry.kubeStateMetrics.metricLabelsAllowlist exporta os labels de tipo de
capacidade que o painel de spot do Deck lê.
O node-exporter roda como DaemonSet em um namespace próprio, criado pelo chart,
<release>-node (Pod Security enforce=privileged), porque monta caminhos do host. O
orbit-node, engine padrão, fica na rede do pod e no próprio namespace de PID, e monta seis
caminhos do host somente leitura em /host/root: /proc/1/net (a rede do node, pelo seu
init), /proc/1/mountinfo, /sys/class/net e o /sys/devices para onde ele aponta,
/run/udev/data e /etc/os-release, além de /var/log/pods com telemetry.logs e do
diretório de cada fonte de telemetry.logs.files (logs.md). O
/proc e o /sys do próprio pod dão os contadores do kernel. O node-exporter
(engine: upstream) precisa, em vez disso, de hostPID, hostNetwork e do / do node
em /host/root. O orbit-node escuta no IP do pod, o upstream no próprio IP do node, os
dois na porta telemetry.nodeExporter.port (padrão 9111, nunca 9100: o chart
recusa essa porta para o upstream não colidir com um node-exporter que o cluster já
rode; duas releases no mesmo cluster precisam de duas portas). O coletor de sistema de
arquivos exclui os pontos de montagem virtuais de sempre mais os montados pelos próprios
runtimes de container (run/containerd, var/lib/containers/storage: containerd na EKS
e no Bottlerocket) via telemetry.nodeExporter.mountPointsExclude. Roda com
runAsNonRoot (65534), readOnlyRootFilesystem, todas as capabilities descartadas,
seccomp RuntimeDefault. Não precisa de opções de SELinux, mesmo no Bottlerocket, já
que o label container_t padrão já cobre o que o container lê. Tolera qualquer
taint por padrão, e uma afinidade de node o mantém fora do Fargate, onde DaemonSets
não rodam.
telemetry.nodeExporter.engine: orbit, o padrão, roda o orbit-node (o exporter em Rust,
services/rust/orbit-node) no mesmo DaemonSet, com a mesma porta, montagens, exclusões
e labels: as famílias, os valores de label e as unidades do node-exporter, menos os
go_* do runtime Go, os promhttp_* e o node_exporter_build_info, com cerca de um
terço da memória e da CPU. A imagem é telemetry.nodeExporter.orbit.image, fixada por
digest como as imagens do produto. upstream roda o próprio node-exporter.
Com networkPolicy.enabled, o agente pode alcançar o orbit-stack na 8082, o
kube-state-metrics na 8080, a porta 9090 de cada componente, e os CIDRs de node
(telemetry.agent.networkPolicy.nodeCIDRs, com as faixas privadas como padrão) apenas
nas portas 10250 e a do node-exporter, e nada além disso. A aplicação depende
da CNI: o k3s (e por extensão o k3d) a impõe através do seu controlador
kube-router embutido; o flannel sozinho não impõe; Calico e Cilium impõem; na EKS, só com
o agente de políticas de rede da VPC CNI ligado. Onde nada impõe essas regras, os objetos
são aplicados e não bloqueiam nada, e a instalação continua funcionando.
Uma ressalva sobre o Cilium: nele, um ipBlock nunca casa com o endereço de um node, a
menos que o policy-cidr-match-mode do Cilium esteja em nodes; ajuste isso, ou as coletas
do kubelet, do cAdvisor e do node-exporter serão descartadas.
networkPolicy.apiServerCIDRs vem vazio por padrão; numa CNI que impõe políticas, isso
deixa o agente sem conseguir descobrir alvos e o kube-state-metrics sem conseguir listar
nada, e o NOTES.txt avisa sobre isso depois da instalação.
Confirme que o engine está recebendo amostras:
kubectl -n sreorbit port-forward svc/sreorbit-orbit-stack 8082:8082 &curl -fsS localhost:8082/api/v1/query --data-urlencode 'query=count by (job) ({__name__=~".+"})' \ -H "Authorization: Bearer $ORBIT_STACK_AUTH_TOKEN"(o cabeçalho Authorization só quando a autenticação do orbit-stack é estática). Cada job
listado acima deve mostrar uma contagem maior que zero.
Atualize
O mesmo comando da instalação (helm upgrade --install é idempotente), com digests novos
para o que você publicou:
helm upgrade --install sreorbit deploy/helm/sreorbit \ --namespace sreorbit \ -f deploy/helm/sreorbit/values-prod.yaml -f digests.yaml \ --set ingress.host=YOUR_REAL_HOSTNAME \ --set ingress.tls.secretName=YOUR_TLS_SECRET_NAME \ --set secrets.existingSecret=sreorbit-secrets \ --set secrets.create=false \ --timeout 5m --waitmaxUnavailable: 0, maxSurge: 1 em cada Deployment com mais de uma réplica significa que a
capacidade nunca cai durante o rollout: um pod novo sobe e passa no readiness antes de um
antigo ser removido. Os dois componentes com volume, orbit-api (com a persistência ligada)
e orbit-stack, rodam uma réplica com Recreate: o pod antigo para antes de o novo montar
o claim, então o rollout deles tem uma breve interrupção, e nada do que está no volume se
perde.
Faça rollback
helm -n sreorbit history sreorbithelm -n sreorbit rollback sreorbitIsto é idêntico byte a byte ao que você testou porque você instalou com digests: o
helm rollback reaplica a release registrada, e um digest não pode derivar para bytes
diferentes do jeito que uma tag pode. Se um rollback não bater com o que você testou, veja
troubleshooting.md; numa instalação feita sobre uma tag pura, suspeite primeiro da tag.
Desinstale de forma limpa
helm -n sreorbit uninstall sreorbitO Secret de credenciais carrega helm.sh/resource-policy: keep quando é o chart que o cria
(não quando você usou secrets.existingSecret, que o Helm nunca possuiu). Ele sobrevive à
desinstalação de propósito, para que uma reinstalação não regenere credenciais das quais
você ainda depende em outro lugar. Remova-o você mesmo quando terminar:
kubectl -n sreorbit delete secret sreorbit-secrets # only if the chart created itkubectl delete namespace sreorbit # removes everything elseTraces e a loja de demonstração
O engine recebe traces do OpenTelemetry na mesma porta e com o mesmo bearer do remote-write,
em http://<release>-orbit-stack.<namespace>.svc.cluster.local:8082/v1/traces; com
networkPolicy.enabled, acrescente antes o namespace do seu Collector ou das suas aplicações
a components.orbit-stack.networkPolicy.allowFromNamespaces.
O ../apm.md traz a configuração do exporter.
Para ver o APM com tráfego antes que os seus próprios serviços enviem qualquer coisa, ligue a
loja de demonstração: oito pequenos serviços e um gerador de carga a partir da imagem do
orbit-stack, cada um no seu próprio Deployment, enviando traces para o engine com o bearer
dele:
helm upgrade sreorbit deploy/helm/sreorbit -n sreorbit --reuse-values \ --set demo.shop.enabled=truedemo.shop.rps define a carga (padrão de 5 requisições por segundo) e demo.shop.resources,
os requests e limits dos pods; --set demo.shop.enabled=false remove tudo de novo. A loja
precisa de components.orbit-stack.enabled e vem desligada por padrão, porque é uma carga
que você não pediu.
O volume do engine
components.orbit-stack.persistence (ligado por padrão, 20Gi) renderiza um
PersistentVolumeClaim chamado <release>-orbit-stack-data com
helm.sh/resource-policy: keep, de modo que o helm uninstall deixa a telemetria para trás
para você apagar deliberadamente. Com storageClassName vazio, vale a classe padrão do
cluster, exceto na EKS (uma versão de servidor contendo -eks-) ou com
requireStorageClass: true: aí o render se recusa, em vez de deixar o claim esperando por
um padrão que talvez nem exista. Informe uma storageClassName já existente, ou defina
storageClass.create: true para o chart provisionar uma sozinho (veja "Amazon EKS" logo
abaixo para os detalhes do EBS). Um claim que já existe mantém a classe com que foi
vinculado, porque esse campo é imutável. O engine roda uma réplica com estratégia Recreate porque o claim
é ReadWriteOnce. O claim também o prende a uma zona de disponibilidade, então o agente, o
coletor OTLP e o orbit-api preferem essa zona (um podAffinity preferencial de peso 100 nos
pods dele): o tráfego deles até o orbit-stack fica fora da cobrança entre zonas, e uma zona
cheia ainda os agenda em outra. O affinity do próprio componente substitui essa preferência
(no orbit-api, o global também). Dimensione-o para o ORBIT_STACK_RETENTION nos seus bytes por amostra
(../benchmark.md mediu 1,7 B em uma carga com formato de scrape) mais
uma duração de bloco de write-ahead log. Aponte qualquer agente seu para
http://<release>-orbit-stack.<namespace>.svc.cluster.local:8082/api/v1/write com o bearer
acima, como o agente do próprio chart (veja "Telemetria" acima) já faz;
../orbit-stack.md tem a configuração completa.
Amazon EKS
deploy/helm/sreorbit/values-eks.yaml é o overlay para EKS: o produto inteiro em qualquer
cluster EKS, por cima dos padrões do próprio chart (values.yaml). O cluster só precisa fornecer um
ingress controller e o add-on do driver CSI da Amazon EBS (com sua IAM role) para o volume
do orbit-stack; nada aqui pressupõe um endpoint de API público, já que o chart fala com o
cluster de dentro dele.
helm upgrade --install sreorbit deploy/helm/sreorbit -n sreorbit \ -f deploy/helm/sreorbit/values-eks.yaml \ --set-string secrets.orbitAuthToken="$(openssl rand -hex 32)" \ --set-string secrets.nocturneAuthToken="$(openssl rand -hex 32)" \ --set-string secrets.orbitStackAuthToken="$(openssl rand -hex 32)"Tokens passados desse jeito rotacionam a cada nova execução; em produção, gerencie um Secret
você mesmo e defina secrets.existingSecret, como já visto acima. Sem um administrador no
Secret, o orbit-api desta instalação registra no log um código de configuração de uso único
para o primeiro login ("O primeiro administrador, e o volume do orbit-api" acima).
O values-eks.yaml define components.web.auth.enabled como true, então este overlay
liga o Basic auth próprio do web e o combina com ingress.basicAuth.enabled: false.
O quickstart acima não define WEB_AUTH_USER nem WEB_AUTH_VERIFIER; acrescente as
duas ao Secret do release (sreorbit-secrets, ou o que secrets.existingSecret
apontar; veja "O próprio login do web" acima) antes de o web conseguir subir, ou o pod
fica em CreateContainerConfigError. O mesmo values-eks.yaml também limita
as requisições na borda com nginx.ingress.kubernetes.io/limit-rps: "20" e
nginx.ingress.kubernetes.io/limit-connections: "20"; aumente os dois quando
muitos operadores compartilharem um único endereço NAT.
ingress.className é um CHANGEME (kubectl get ingressclass; muitos clusters não têm
classe padrão). O overlay também define ingress.controller
(nginx/traefik/haproxy/alb/none; vazio deriva da className), que escolhe as
anotações seguras para SSE e decide se o basic auth é permitido; assim, uma classe chamada
por exemplo nginx-internal ainda recebe as anotações do nginx. TLS é opcional.
ingress.basicAuth.{enabled,secretName,realm} coloca uma senha na frente de todo o console
via anotações do ingress-nginx, lendo um arquivo htpasswd de um Secret com a chave auth; o
render falha se o basic auth estiver ligado e o controller não for nginx.
Ligar ingress.basicAuth.enabled junto com components.web.auth.enabled é a única
combinação que o chart se recusa a renderizar: o ingress-nginx remove o cabeçalho
Authorization assim que o próprio basic auth dele aceita a credencial, então o web nunca
chegaria a ver nenhuma credencial para checar, e passaria a rejeitar toda requisição por
conta própria. Escolha uma camada, não as duas.
A persistência do orbit-stack, e a do orbit-api, pressupõem que não existe StorageClass
padrão: storageClass.create: true provisiona por conta própria a <release>-orbit-stack e
a <release>-orbit-api (ebs.csi.aws.com, gp3, criptografadas, WaitForFirstConsumer,
allowVolumeExpansion, Retain; todo campo de cada uma é imutável depois de criada). No EKS Auto Mode, o EBS é provisionado pelo driver
próprio dele: lá, defina storageClass.provisioner como ebs.csi.eks.amazonaws.com.
requireStorageClass: true faz o render falhar se nem storageClassName nem
storageClass.create estiverem definidos. Um PVC preso em Pending significa que falta o
driver CSI ou a IAM role dele, e o NOTES.txt avisa isso.
networkPolicy.apiServerCIDRs merece o mesmo cuidado: na EKS, kubernetes.default é o
primeiro endereço do CIDR de serviços do cluster, e os endpoints dele são as ENIs do control plane na porta
443. Registre os dois: o agente de políticas de rede da VPC CNI julga o próprio IP do
Service, antes da reescrita do kube-proxy, enquanto Calico e Cilium julgam os endpoints:
kubectl get svc kubernetes -n defaultkubectl get endpointslices -n default -l kubernetes.io/service-name=kubernetesO Nocturne continua no provedor mock; o caminho de escrita fica desligado
(rbac.write.enabled: false, ORBIT_WRITE_ENABLED: "false"); ORBIT_DEMO_DATA: "false"
junto com orbit-api e seu rbac.enabled: true dá, em vez disso, um console ao vivo e
somente leitura do cluster real. image.registry e telemetry.*.image.registry também podem ser
sobrescritos para um mirror privado no ECR.
Para onde ir em seguida
- Cada variável citada acima:
../configuration.md. - O que os objetos NetworkPolicy que esta instalação criou impõem e não impõem na CNI do
seu cluster:
../security.md. - Helm não permitido:
kubectl.md.