Pular para o conteúdo

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

RequisitoVersãoPor quê
Kubernetes1.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.
Helm3.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.
kubectlcompatível com a versão minor do seu clusterOs comandos de verificação e de acompanhamento de rollout abaixo.
Um ingress controllero values-prod.yaml pressupõe nginx (ingress.className: nginx); o chart renderiza automaticamente anotações seguras para SSE para essa classeDefina 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 modernoResolver os digests das imagens antes de uma instalação de produção; veja abaixo.
Imagens publicadas em um registry que você controlan/aO 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:

bash
kubectl version --clienthelm version

Antes da sua primeira instalação em produção

Quatro coisas, nesta ordem, tiradas do próprio cabeçalho do values-prod.yaml:

  1. Aponte ingress.host para um nome DNS real que você controla.
  2. 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.
  3. Crie o Secret de credenciais fora do chart (abaixo) e defina secrets.existingSecret.
  4. 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

bash
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):

bash
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:

bash
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=sreorbit

O 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:

bash
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:

bash
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:

bash
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=false

As 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:

bash
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 VERIFIER

As três chaves são opcionais (secretKeyRef com optional: true) e são lidas uma única vez, quando o contêiner sobe:

  • ORBIT_ADMIN_USER e ORBIT_ADMIN_PASSWORD_VERIFIER criam esse administrador só enquanto não existe nenhum usuário, e depois disso são ignoradas. Sem as duas, o orbit-api registra no log um código de configuração de uso único: kubectl -n sreorbit logs deploy/sreorbit-orbit-api | grep setup_code; em seguida, abra https://YOUR_REAL_HOSTNAME/login.
  • ORBIT_SESSION_SECRET assina 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:

bash
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):

bash
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

bash
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 \  | less

Leia 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

bash
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 --wait

Sem --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

bash
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=sreorbit

Todo 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

bash
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-forward

A ú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.

ComponentePadrão (orbit)Upstream, ainda selecionávelO que faz
Agente de scrapeorbit-agentquay.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-metricsorbit-stateregistry.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-exporterorbit-nodequay.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):

JobAlvo
kubeletInternalIP:10250 de cada node, com o token da própria ServiceAccount do agente; só com engine: prometheus, já que nada o consulta
cadvisorO mesmo host, em /metrics/cadvisor
kube-state-metricsDescoberta por EndpointSlice no namespace da release
node-exporterDescoberta de pods em <release>-node
sreorbitAs 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:

bash
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:

bash
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 --wait

maxUnavailable: 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

bash
helm -n sreorbit history sreorbithelm -n sreorbit rollback sreorbit

Isto é 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

bash
helm -n sreorbit uninstall sreorbit

O 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:

bash
kubectl -n sreorbit delete secret sreorbit-secrets   # only if the chart created itkubectl delete namespace sreorbit                     # removes everything else

Traces 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:

bash
helm upgrade sreorbit deploy/helm/sreorbit -n sreorbit --reuse-values \  --set demo.shop.enabled=true

demo.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.

bash
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:

bash
kubectl get svc kubernetes -n defaultkubectl get endpointslices -n default -l kubernetes.io/service-name=kubernetes

O 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