Pular para o conteúdo

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

RequisitoVersãoPor quê
Dockerrecente (validado com o Docker Engine 29.1.3)Roda os nodes do k3d como contêineres e constrói as imagens.
k3d5.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.
kubectlcompatível com o k3s v1.35Conversa com o cluster local
helm3.x (validado com 3.16.4)O up.sh instala o chart com values-dev.yaml.
nodequalquer versão recenteO 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 WSL2n/aVeja "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.
bash
docker --version && k3d version && kubectl version --client && helm version

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

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

bash
docker stats --no-stream $(docker ps --filter name=k3d-sreorbit -q)kubectl top nodes

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

bash
curl -fsS -u dev:sreorbit-dev-only http://sreorbit.localhost:8090/api/v1/auth/state

O /healthz não precisa de credencial de nenhum jeito:

bash
curl -fsS http://sreorbit.localhost:8090/healthz

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

bash
kubectl --context k3d-sreorbit-dev -n sreorbit logs deploy/sreorbit-orbit-api | grep setup_code

Abra 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"):

bash
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/clusters

Instale

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

bash
make k3d-up

Equivalente sem make (lê o mesmo ambiente que o make passaria; TAG, REGISTRY e VERSION têm defaults funcionais):

bash
./deploy/k3d/up.sh

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

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

text
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

bash
kubectl -n sreorbit get deploy,pod,svc,ingresskubectl -n sreorbit rollout status deploy/sreorbit-web --timeout=180s

Todo 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

bash
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 %1

Atualize

bash
make k3d-deploy

Equivalente:

bash
SKIP_BUILD= ./deploy/k3d/up.sh

Reconstrói, reimporta e roda helm upgrade de novo, sem recriar o cluster.

Faça rollback

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

O 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

bash
make k3d-down

Equivalente, e apaga o cluster inteiro mais o registry dele:

bash
./deploy/k3d/down.sh

Para desinstalar apenas a release do Helm e manter o cluster (mais rápido se você vai reinstalar em seguida):

bash
KEEP_CLUSTER=1 ./deploy/k3d/down.sh

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

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

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