Skip to content

Commit a3a011f

Browse files
heraqueheraque
committed
Adiciona arquivos de configuração e documentação para a imagem de debug não-root
1 parent 6368767 commit a3a011f

4 files changed

Lines changed: 308 additions & 1 deletion

File tree

‎.dockerignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Evita enviar lixo de git e artefatos locais para o contexto de build.
2+
.git
3+
.github
4+
.DS_Store
5+
*.log

‎.github/workflows/publish.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: publish
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
tags:
8+
- "v*"
9+
pull_request:
10+
11+
permissions:
12+
contents: read
13+
packages: write
14+
attestations: write
15+
id-token: write
16+
17+
concurrency:
18+
group: publish-${{ github.ref }}
19+
cancel-in-progress: true
20+
21+
jobs:
22+
docker:
23+
runs-on: ubuntu-latest
24+
25+
steps:
26+
# Baixa o repositorio para montar a imagem a partir do Dockerfile versionado.
27+
- name: Checkout
28+
uses: actions/checkout@v5
29+
30+
# Habilita emulacao para publicar amd64 e arm64 a partir do runner padrao.
31+
- name: Set up QEMU
32+
uses: docker/setup-qemu-action@v3
33+
34+
# Prepara o builder Buildx com suporte a multiplataforma e cache.
35+
- name: Set up Docker Buildx
36+
uses: docker/setup-buildx-action@v4
37+
38+
# Faz login no GHCR usando o token nativo do workflow, como recomendado pela documentacao do GitHub.
39+
- name: Log in to GHCR
40+
if: github.event_name != 'pull_request'
41+
uses: docker/login-action@v4
42+
with:
43+
registry: ghcr.io
44+
username: ${{ github.actor }}
45+
password: ${{ secrets.GITHUB_TOKEN }}
46+
47+
# Gera tags e labels OCI automaticamente para branch main, semver e SHA curto.
48+
- name: Extract Docker metadata
49+
id: meta
50+
uses: docker/metadata-action@v5
51+
with:
52+
images: ghcr.io/${{ github.repository_owner }}/debugtools
53+
tags: |
54+
type=raw,value=main,enable=${{ github.ref == 'refs/heads/main' }}
55+
type=semver,pattern={{version}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
56+
type=semver,pattern={{major}}.{{minor}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
57+
type=sha,format=short
58+
59+
# Monta a imagem, roda o build multiplataforma e publica no GHCR fora de pull request.
60+
- name: Build and push
61+
id: build
62+
uses: docker/build-push-action@v7
63+
with:
64+
context: .
65+
file: ./Dockerfile
66+
platforms: linux/amd64,linux/arm64
67+
pull: true
68+
push: ${{ github.event_name != 'pull_request' }}
69+
tags: ${{ steps.meta.outputs.tags }}
70+
labels: ${{ steps.meta.outputs.labels }}
71+
cache-from: type=gha
72+
cache-to: type=gha,mode=max
73+
74+
# Publica atestacao de proveniencia apenas quando a imagem realmente foi enviada ao GHCR.
75+
- name: Attest build provenance
76+
if: github.event_name != 'pull_request'
77+
uses: actions/attest-build-provenance@v2
78+
with:
79+
subject-name: ghcr.io/${{ github.repository_owner }}/debugtools
80+
subject-digest: ${{ steps.build.outputs.digest }}
81+
push-to-registry: true

‎Dockerfile‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Usa a release estavel mais nova do Alpine verificada em 19/05/2026.
2+
FROM alpine:3.23.4
3+
4+
# Define shell estrito para falhar cedo durante a montagem da imagem.
5+
SHELL ["/bin/sh", "-euxo", "pipefail", "-c"]
6+
7+
# Instala apenas o ferramental generico que o SRE realmente usa em debug de rede,
8+
# TLS, DNS, processos e leitura de artefatos estruturados.
9+
RUN apk add --no-cache \
10+
bash \
11+
bind-tools \
12+
busybox-extras \
13+
ca-certificates \
14+
coreutils \
15+
curl \
16+
file \
17+
findutils \
18+
gawk \
19+
grep \
20+
iproute2 \
21+
iputils \
22+
jq \
23+
netcat-openbsd \
24+
openssl \
25+
procps \
26+
sed \
27+
socat \
28+
util-linux \
29+
wget \
30+
yq \
31+
&& addgroup -g 10001 -S sre \
32+
&& adduser -u 10001 -S -D -G sre -h /home/sre sre \
33+
&& mkdir -p /home/sre /workspace \
34+
&& chown -R 10001:10001 /home/sre /workspace
35+
36+
# Expõe metadados padrao para rastreabilidade e compatibilidade com tooling OCI.
37+
LABEL org.opencontainers.image.title="debugTools" \
38+
org.opencontainers.image.description="Imagem enxuta de diagnostico SRE nao-root para containers efemeros no Kubernetes" \
39+
org.opencontainers.image.source="https://github.com/heraque/debugTools" \
40+
org.opencontainers.image.licenses="MIT"
41+
42+
# Define ambiente previsivel para shells, certificados e area de trabalho.
43+
ENV HOME=/home/sre \
44+
TERM=xterm-256color \
45+
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
46+
47+
# Garante compatibilidade com policies runAsNonRoot usando UID/GID numericos.
48+
USER 10001:10001
49+
WORKDIR /workspace
50+
51+
# Mantem a imagem util para execucao interativa e comandos injetados pelo wrapper.
52+
CMD ["/bin/bash"]

‎README.md‎

Lines changed: 170 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,170 @@
1-
# debugTools
1+
# debugTools
2+
3+
Imagem de debug não-root para uso em containers efêmeros de diagnóstico no Kubernetes.
4+
5+
## Objetivo
6+
7+
Esta imagem existe para substituir o uso genérico de `nicolaka/netshoot` em cenários onde o workload alvo exige `runAsNonRoot` e políticas mais rígidas de segurança.
8+
9+
Ela foi desenhada para uso geral em troubleshooting Kubernetes com `kubectl debug`, especialmente quando o caso exige toolbox de rede, DNS e TLS dentro do pod alvo.
10+
11+
## Para que serve
12+
13+
Use esta imagem quando o operador precisar:
14+
15+
- validar DNS, TCP e TLS a partir do namespace/pod real;
16+
- inspecionar resolução de nomes, rotas e sockets;
17+
- fazer `GET`/`HEAD` idempotentes para health checks;
18+
- analisar certificados, cadeias TLS e handshake;
19+
- consultar JSON/YAML/texto com ferramentas simples e previsíveis;
20+
- operar em pods com `runAsNonRoot`, sem depender de imagem root.
21+
22+
## O que esta imagem entrega
23+
24+
Ferramental incluído:
25+
26+
- `bash`
27+
- `bind-tools` (`dig`, `nslookup`)
28+
- `busybox-extras`
29+
- `ca-certificates`
30+
- `coreutils`
31+
- `curl`
32+
- `file`
33+
- `findutils`
34+
- `gawk`
35+
- `grep`
36+
- `iproute2` (`ip`, `ss`)
37+
- `iputils`
38+
- `jq`
39+
- `netcat-openbsd` (`nc`)
40+
- `openssl`
41+
- `procps`
42+
- `sed`
43+
- `socat`
44+
- `util-linux`
45+
- `wget`
46+
- `yq`
47+
48+
Características operacionais:
49+
50+
- base `alpine:3.23.4`
51+
- usuário numérico fixo `10001:10001`
52+
- `WORKDIR=/workspace`
53+
- imagem pequena o suficiente para uso recorrente, mas completa para diagnóstico de rede/TLS
54+
55+
## O que esta imagem não tenta ser
56+
57+
Esta imagem não tenta virar toolbox universal sem critério.
58+
59+
Ela deliberadamente não inclui por padrão:
60+
61+
- `kubectl`
62+
- `helm`
63+
- `tcpdump`
64+
- clientes específicos de banco (`psql`, `redis-cli`, `mysql`, `mongo`)
65+
- toolchains de build
66+
- Python/Node/Go só para scripting ad hoc
67+
68+
Motivo:
69+
70+
- isso aumenta tamanho, superfície de ataque e drift;
71+
- boa parte desses binários não é necessária para a maioria dos diagnósticos read-only no Kubernetes;
72+
- o objetivo aqui é resolver bem a trilha de conectividade, DNS, TLS, sockets e parsing leve.
73+
74+
Se algum binário extra virar necessidade recorrente e justificada por evidência real, ele deve ser adicionado conscientemente, não por conveniência.
75+
76+
## Como usar
77+
78+
### 1. Publicar no GHCR
79+
80+
O workflow em `.github/workflows/publish.yml` publica a imagem em:
81+
82+
```text
83+
ghcr.io/heraque/debugtools
84+
```
85+
86+
Fluxo esperado:
87+
88+
1. subir mudanças na branch `main`;
89+
2. deixar o GitHub Actions buildar e publicar;
90+
3. preferir tags versionadas para produção, por exemplo `v0.1.0`;
91+
4. evitar depender de `:main` por muito tempo em ambientes estáveis.
92+
93+
### 2. Build local
94+
95+
```bash
96+
docker build -t debugtools:test .
97+
```
98+
99+
### 3. Teste local rápido
100+
101+
```bash
102+
docker run --rm debugtools:test sh -lc 'id && dig -v | head -n 1 && openssl version && jq --version'
103+
```
104+
105+
### 4. Uso manual com kubectl debug
106+
107+
Exemplo ilustrativo:
108+
109+
```bash
110+
kubectl debug pod/app-123 \
111+
-n app-ns \
112+
--target=app \
113+
--image=ghcr.io/heraque/debugtools:v0.1.0 \
114+
--container=debugger \
115+
-- bash
116+
```
117+
118+
## Uso em automações e wrappers
119+
120+
Esta imagem pode ser consumida por wrappers, automações de diagnóstico ou uso manual com `kubectl debug`.
121+
122+
Contrato operacional esperado:
123+
124+
- usar somente em diagnóstico controlado;
125+
- preferir primeiro o runtime nativo do container alvo quando ele já tiver os binários necessários;
126+
- subir para um container efêmero quando:
127+
- faltarem binários no container alvo;
128+
- a prova precisar vir do runtime/pod real;
129+
- o caso exigir toolbox de rede/TLS mais completo.
130+
131+
## Casos típicos de uso
132+
133+
- testar `tcp` e `tls` para `kubernetes.default.svc:443`
134+
- validar SNI e trust chain de um endpoint interno
135+
- confirmar DNS dentro do pod quando a aplicação não tem `dig`/`nslookup`
136+
- analisar `curl -I`/`wget --spider` em endpoints de health
137+
- checar `ss -plant` ou `ip route` durante falha de conectividade
138+
- inspecionar resposta HTTP sem depender de shell livre fora do fluxo de diagnóstico
139+
140+
## Segurança e trade-offs
141+
142+
Pontos de desenho:
143+
144+
- não-root por padrão para compatibilidade com `runAsNonRoot`
145+
- sem privilégio adicional
146+
- sem capabilities extras por padrão
147+
- foco em diagnóstico read-only
148+
149+
Trade-off aceito:
150+
151+
- a imagem não é a menor possível em bytes absolutos;
152+
- ela é pequena o bastante para uso operacional e grande o bastante para evitar fallback tosco durante incidentes reais.
153+
154+
## Versionamento recomendado
155+
156+
Para uso operacional estável:
157+
158+
- publique com tag semântica, por exemplo `v0.1.0`
159+
- fixe o chart/consumer nesse tag
160+
- use `:main` apenas como trilha de desenvolvimento
161+
162+
## Quando evoluir esta imagem
163+
164+
Vale mexer nela quando houver evidência recorrente de que falta uma capacidade necessária ao troubleshooting real, por exemplo:
165+
166+
- debugging de DNS/TLS insuficiente;
167+
- parsing estrutural insuficiente;
168+
- incompatibilidade com políticas comuns de segurança de workload.
169+
170+
Não vale mexer nela só porque “pode ser útil algum dia”.

0 commit comments

Comments
 (0)