Instalação
Loop local com k3d
Um cluster Kubernetes real e descartável no seu laptop. Este caminho exercita de verdade
topologySpreadConstraints e PodDisruptionBudgets (o Docker Compose não consegue; um
cluster k3d de um node com agents: 0 também quase não consegue). Use-o quando quiser ver o
hardening específico de Kubernetes fazendo alguma coisa antes de tocar um cluster real.
A NetworkPolicy não é mais exceção: o k3s (e portanto o k3d) a impõe de fábrica,
através do seu controlador kube-router embutido (o flannel sozinho só cuida da camada de
rede overlay), então este loop também exercita de verdade as NetworkPolicies de
telemetria. O security.md lista o que o kube-router permite e bloqueia aqui.
Pré-requisitos
| Requisito | Versão | Por quê |
|---|---|---|
| Docker | recente (validado com o Docker Engine 29.1.3) | Roda os nodes do k3d como contêineres e constrói as imagens. |
k3d | 5.9.0+ (validado com 5.9.0; a configuração do cluster trava rancher/k3s:v1.35.5-k3s1, o default do próprio k3d 5.9.0) | Cria o cluster. |
kubectl | compatível com o k3s v1.35 | Conversa com o cluster local |
helm | 3.x (validado com 3.16.4) | O up.sh instala o chart com values-dev.yaml. |
node | qualquer versão recente | O up.sh faz o hash da senha de desenvolvimento na primeira execução; veja "O próprio login do web" abaixo. |
| 4 GiB livres para o Docker Desktop / a VM do WSL2 | n/a | Veja "Quanto custa" abaixo: reserve ~2,5 GiB de pico enquanto as imagens são importadas, além do que os próprios nodes do k3d consomem ociosos. |
docker --version && k3d version && kubectl version --client && helm versionQuanto custa
Medido na configuração de cluster deste repositório, ocioso, logo após a criação, com Traefik, CoreDNS, local-path-provisioner e metrics-server no ar e nada nosso implantado ainda:
k3d-sreorbit-dev-server-0 848 MiB
k3d-sreorbit-dev-agent-1 192 MiB
k3d-sreorbit-dev-agent-0 156 MiB
k3d-sreorbit-dev-serverlb 28 MiB
k3d-sreorbit-registry 4 MiB
k3d-sreorbit-dev-tools 3 MiB
--------
~1.2 GiB (1234 MiB measured)Com web, orbit-api, nocturne e orbit-stack implantados com values-dev.yaml (uma
réplica cada) e Ready, a mesma medição marca ~1,5 GiB (1.474 MiB): os quatro workloads
custam cerca de 240 MiB acima do cluster ocioso. Os três pods de backend ficavam em 2 a 3 MiB
cada quando isto foi medido, ainda nas imagens Go, e o web é o resto. Reserve ~2,5 GiB de pico enquanto as imagens são importadas.
Reproduza você mesmo:
docker stats --no-stream $(docker ps --filter name=k3d-sreorbit -q)kubectl top nodesPara reduzir pela metade: defina agents: 0 em deploy/k3d/cluster.yaml antes de criar
o cluster. Um cluster de node único custa aproximadamente metade da pegada ociosa acima e
perde a única coisa para a qual um cluster de 3 nodes serve aqui: ver
topologySpreadConstraints e PodDisruptionBudgets fazerem algo real em vez de serem YAML
decorativo.
Autenticação neste caminho: desligada, de propósito
O values-dev.yaml define NOCTURNE_AUTH_MODE e ORBIT_STACK_AUTH_MODE como disabled, e
ORBIT_AUTH_MODE como static com um bearer que o up.sh gera e mantém no Secret da release
(dados de cluster ao vivo recusam disabled). Este é o único caminho de instalação em que
isso está correto de fábrica. O ORBIT_AUTH_MODE é a exceção porque o up.sh
instala com ORBIT_DEMO_DATA=false (veja "O que o console mostra neste loop" abaixo), e o
modo disabled é recusado de imediato sempre que os dados de demonstração estão desligados
(veja security.md), então a fonte do próprio console mantém um bearer real enquanto os
dois serviços internos não. Você verá um WARN nomeando o risco nos logs dos dois serviços de backend a
cada inicialização. Aqui ele é esperado; a mesma linha em um cluster com dados reais é o
seu sinal para parar.
O próprio login do web
O web também autentica cada requisição aqui com HTTP Basic (páginas, o Deck, toda
chamada /api/*, arquivos estáticos), igual a qualquer outro caminho de instalação; só o
GET /healthz fica isento. O values-dev.yaml liga isso, mas o up.sh usa uma
credencial de desenvolvimento fixa em vez de pedir para você gerar uma: usuário dev,
senha sreorbit-dev-only. A senha é pública de propósito, e só é aceitável porque este
cluster é local e descartável. O up.sh guarda isso no Secret da release na primeira
execução (fazer o hash dela precisa de node no host; veja "Pré-requisitos" acima) e
reaproveita esse mesmo Secret em toda execução seguinte, então a senha não muda debaixo
de você entre chamadas do up.sh.
Um navegador acessando http://sreorbit.localhost:8090/ pede a credencial. O curl
precisa de -u, e toda rota de API, exceto as de login, também exige uma sessão (próxima
seção):
curl -fsS -u dev:sreorbit-dev-only http://sreorbit.localhost:8090/api/v1/auth/stateO /healthz não precisa de credencial de nenhum jeito:
curl -fsS http://sreorbit.localhost:8090/healthzO primeiro login
Essa senha abre o site; depois, o console pergunta quem você é. O values-dev.yaml roda o
orbit-api sobre os dados ao vivo deste cluster, sem administrador no Secret, então na
primeira inicialização ele registra no log um código de configuração de uso único:
kubectl --context k3d-sreorbit-dev -n sreorbit logs deploy/sreorbit-orbit-api | grep setup_codeAbra http://sreorbit.localhost:8090/login, informe o código junto com um nome de usuário,
um nome e uma senha de 12 caracteres ou mais, e você entra como o primeiro administrador. O
código muda a cada reinício do orbit-api enquanto não existir um administrador, e depois
disso deixa de existir. Usuários, sessões, dashboards e a trilha de auditoria ficam em um
claim pequeno (components.orbit-api.persistence, 256Mi aqui), então sobrevivem a um
make k3d-deploy; o make k3d-down os apaga junto com o cluster. Pelo shell, faça login
através do web com um cookie jar, depois de gravar as credenciais em login.json
(../identity.md → "Como entrar"):
curl -fsS -u dev:sreorbit-dev-only -c k3d.cookies -H 'content-type: application/json' \ --data @login.json http://sreorbit.localhost:8090/api/v1/auth/logincurl -fsS -u dev:sreorbit-dev-only -b k3d.cookies http://sreorbit.localhost:8090/api/v1/clustersInstale
O repositório não é público, e nada nesta página o baixa: este loop constrói as
imagens a partir da árvore de código-fonte do SRE Orbit que você recebeu. Rode-o na raiz
dessa árvore, o diretório que contém o Makefile e o deploy/.
make k3d-upEquivalente sem make (lê o mesmo ambiente que o make passaria; TAG, REGISTRY e
VERSION têm defaults funcionais):
./deploy/k3d/up.shIsto, nesta ordem: cria o cluster sreorbit-dev se ele ainda não existir (é seguro rodar de
novo: reaproveita um cluster existente), constrói cada imagem que o chart roda com o
values-dev.yaml (o web e cada serviço em Rust a partir de services/rust/<name>, do jeito
que o cabeçalho do Dockerfile dele documenta, incluindo os engines orbit-*), faz
k3d image import delas direto para o containerd em cada node
(sem ida e volta a um registry) e roda helm upgrade --install com o values-dev.yaml. O
script pula uma imagem sem Dockerfile e informa isso na própria saída; leia-a. CARGO_BUILD_JOBS=4 limita a compilação em Rust numa máquina
compartilhada.
A configuração do cluster também cria um registry local (localhost:5111 a partir do seu
shell, k3d-sreorbit-registry:5000 de dentro dos pods). O up.sh não o usa (importar a
imagem é mais rápido em um laptop); ele está lá para o loop baseado em push.
Acesse
http://sreorbit.localhost:8090/*.localhost resolve para 127.0.0.1 sem nenhuma edição de /etc/hosts no Linux e no
macOS. No Windows, acrescente a linha você mesmo:
127.0.0.1 sreorbit.localhost(8090/8453 em vez de 80/443, para que o ingress deste cluster nunca
dispute uma porta baixa no mesmo host com a stack do Compose ou com qualquer outra coisa.)
Como é uma instalação saudável
kubectl -n sreorbit get deploy,pod,svc,ingresskubectl -n sreorbit rollout status deploy/sreorbit-web --timeout=180sTodo pod em Running/Ready (uma réplica cada: o values-dev.yaml desliga PDBs e topology
spread com uma réplica, já que os dois não fazem sentido, e o PDB especificamente faz mal,
abaixo disso). Um componente cuja imagem não foi construída aparece em ImagePullBackOff: o
pullPolicy: Never neste caminho faz isso falhar alto em vez de tentar silenciosamente
contra o ghcr.io; veja troubleshooting.md.
Verifique
curl -fsS http://sreorbit.localhost:8090/healthz # exempt: no credential needed curl -fsS -u dev:sreorbit-dev-only http://sreorbit.localhost:8090/api/v1/auth/state # through web's proxy: it attaches the bearer kubectl --context k3d-sreorbit-dev -n sreorbit port-forward svc/sreorbit-orbit-api 8080:8080 &curl -fsS localhost:8080/healthz # probes are exempt on every auth modecurl -fsS localhost:8080/readyz# Everything else on the API listener needs the bearer: values-dev.yaml runs# orbit-api in ORBIT_AUTH_MODE=static, because live cluster data refuses# `disabled`. up.sh generates the token once and keeps it in the release Secret.# Every route but the sign-in ones also needs a session (see "The first sign-in").TOKEN="$(kubectl --context k3d-sreorbit-dev -n sreorbit get secret sreorbit-secrets -o jsonpath='{.data.ORBIT_AUTH_TOKEN}' | base64 -d)"curl -fsS -H "Authorization: Bearer $TOKEN" localhost:8080/api/v1/auth/statekill %1Atualize
make k3d-deployEquivalente:
SKIP_BUILD= ./deploy/k3d/up.shReconstrói, reimporta e roda helm upgrade de novo, sem recriar o cluster.
Faça rollback
helm -n sreorbit rollback sreorbithelm -n sreorbit history sreorbitO values-dev.yaml não define requireDigest, então isto funciona como qualquer outro
rollback de Helm neste caminho. Veja helm.md para a garantia byte a byte que os digests
oferecem, que importa bem menos em um cluster que você está prestes a apagar.
Desinstale de forma limpa
make k3d-downEquivalente, e apaga o cluster inteiro mais o registry dele:
./deploy/k3d/down.shPara desinstalar apenas a release do Helm e manter o cluster (mais rápido se você vai reinstalar em seguida):
KEEP_CLUSTER=1 ./deploy/k3d/down.shAs imagens ficam no seu cache local do Docker de qualquer maneira;
docker rmi ghcr.io/sreorbit/{web,orbit-api,nocturne,orbit-stack}:dev também as remove.
O que o console mostra neste loop
O up.sh constrói o web com NEXT_PUBLIC_DEMO_MODE=false e instala o chart com
ORBIT_DEMO_DATA=false mais o ClusterRole somente-leitura, então o Orbit Deck em
http://sreorbit.localhost:8090/deck mostra este cluster k3d: os três nodes dele, os
workloads do próprio chart, eventos ao vivo, alertas derivados do estado deles, uma
estimativa de FinOps por preço de tabela (ORBIT_NODE_HOURLY_USD é 0, então os nodes do
k3d não custam nada) e telemetria vinda do engine. Essa telemetria agora é do próprio chart: o values-dev.yaml mantém telemetry
ligado nas três peças (o agent, o kube-state-metrics, o node-exporter), com os engines
orbit padrão do chart: o orbit-agent faz scrape do cAdvisor pelos kubelets e do
orbit-state e do orbit-node sob os jobs kube-state-metrics e node-exporter, e faz
remote-write para o orbit-stack, gravando cluster="k3d-sreorbit-dev" em cada série
(o ORBIT_CLUSTER_ID que o Deck já usa). Rodar o up.sh de novo num cluster criado
antes de o chart trazer sua própria telemetria apaga, uma única vez, os objetos
avulsos antigos; o que já tiver o label app.kubernetes.io/managed-by: Helm fica
intocado. Painéis cujas métricas nada no cluster emite (taxa de requisições, taxa de
erro, custo por dia) imprimem "Nenhuma amostra nesta janela." em vez de um desenho. O site
institucional na raiz continua imprimindo o parque de demonstração do CLAIMS.md, em todos os
modos.
O painel ad hoc da página de Observabilidade aceita PromQL contra o engine, por exemplo
sum by (instance) (rate(node_cpu_seconds_total{mode="user"}[5m])), e o salva como um painel
no seu navegador. Os dashboards nativos leem o mesmo fluxo de dados
(../dashboards.md).
O APM fica vazio até que algo envie traces. A loja de demonstração está a um comando de
distância: oito pequenos serviços e um gerador de carga, a partir da imagem que o up.sh já
importou:
helm --kube-context k3d-sreorbit-dev -n sreorbit upgrade sreorbit deploy/helm/sreorbit \ --reuse-values --set demo.shop.enabled=trueO próximo make k3d-deploy instala sem ela outra vez, já que o up.sh não passa
demo.shop.enabled; rode o comando de novo depois dele. O ../apm.md explica o
que a loja faz e o que enviar a partir dos seus próprios serviços.
Para onde ir em seguida
- Cada variável usada pelo
values-dev.yaml:../configuration.md. - O que o kube-router impõe neste cluster, e o que não impõe:
../security.md. - Levar o que você provou aqui para um cluster real:
helm.md.