e0f8e6471c
- best-practices/: 11 topic files + INDEX.md extracted from cluster-bootstrap and custom-claude-skills (validation, k8s, helm, ansible, secrets, debugging, etc.) - settings.yaml: pipeline config (log retention, tracked projects, max logs per run) - CLAUDE.md: updated with best-practices loading and pipeline documentation - memory/log/: first session log demonstrating the format Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
42 lines
1.7 KiB
Markdown
42 lines
1.7 KiB
Markdown
# Debugging Methodology
|
|
|
|
## Check Before You Act
|
|
|
|
- Before writing firewall/network rules, check actual routing (`ip route get <dest>`)
|
|
- Before running config management with variables, ensure values are real, not placeholders
|
|
- Before assuming a container has a shell, `docker inspect` it
|
|
- Before creating API tokens, research all required scopes upfront — iterating one scope at a time costs a push-debug cycle each
|
|
|
|
## Routing and Networking
|
|
|
|
- Always run `ip route get <dest>` on the forwarding host first
|
|
- macvlan, Docker bridge, and other virtual interfaces mean the "obvious" physical interface is often wrong
|
|
- Test from both in-cluster and external perspectives
|
|
|
|
## Full-Chain Testing
|
|
|
|
After wiring up any new service:
|
|
1. Test direct to backend (bypass all proxies)
|
|
2. Test through reverse proxy (bypass DNS)
|
|
3. Test end-to-end as a user would
|
|
|
|
Use `curl --resolve` to test specific paths without depending on DNS propagation.
|
|
|
|
## When Something Doesn't Sync/Apply
|
|
|
|
- Check resource exclusions in the GitOps controller immediately
|
|
- Check if the resource type requires special permissions or labels
|
|
- Check if ServerSideApply conflicts are preventing field changes
|
|
- Don't try workarounds before understanding the root cause
|
|
|
|
## OIDC Integration Checklist
|
|
|
|
Before starting any OIDC integration, research:
|
|
1. What format is the `sub` claim (UUID? username?)
|
|
2. Which claims are in the ID token vs userinfo endpoint
|
|
3. How the consumer matches RBAC identities (groups? email? username?)
|
|
|
|
## Grep Your Own Docs
|
|
|
|
Known issues documented in CLAUDE.md or MEMORY.md but not applied to new scripts/configs waste debugging time. Search your own documentation before writing automation that touches areas with known gotchas.
|