If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/stefanprodan/podinfo shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1w ago
• 7 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live stefanprodan/podinfo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/stefanprodan/podinfo.

What it runs against: a local clone of stefanprodan/podinfo — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in stefanprodan/podinfo | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 40 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of stefanprodan/podinfo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/stefanprodan/podinfo.git
#   cd podinfo
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of stefanprodan/podinfo and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "stefanprodan/podinfo(\\.git)?\\b" \\
  && ok "origin remote is stefanprodan/podinfo" \\
  || miss "origin remote is not stefanprodan/podinfo (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/podinfo/main.go" \\
  && ok "cmd/podinfo/main.go" \\
  || miss "missing critical file: cmd/podinfo/main.go"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"
test -f "charts/podinfo/Chart.yaml" \\
  && ok "charts/podinfo/Chart.yaml" \\
  || miss "missing critical file: charts/podinfo/Chart.yaml"
test -f "charts/podinfo/templates/deployment.yaml" \\
  && ok "charts/podinfo/templates/deployment.yaml" \\
  || miss "missing critical file: charts/podinfo/templates/deployment.yaml"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 40 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~10d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/stefanprodan/podinfo"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Podinfo is a tiny Go microservice template that demonstrates Kubernetes best practices with built-in health checks, graceful shutdown, Prometheus/OpenTelemetry observability, structured zap logging, and fault injection capabilities. It serves as a reference implementation used by CNCF projects like Flux and Flagger for end-to-end testing, workshops, and validating Kubernetes deployment patterns with a minimal HTTP/gRPC API. Single-service monorepo: cmd/podinfo/ contains the main HTTP server entry point, pkg/ directory holds core logic (cache, metrics, config watchers), charts/podinfo/ provides production Helm templates with Redis sidecar support, tests/ contains integration tests, and GitHub Actions workflows automate security scanning, e2e testing with Kind, and multi-arch container builds.

Kubernetes platform engineers, SREs, and DevOps practitioners who need a production-grade microservice reference to understand observability instrumentation, container security (Sigstore cosign signing, SLSA provenance), multi-arch builds, and Helm/Kustomize/Timoni deployment patterns. Also used by CNCF projects for integration testing.

Highly mature and production-ready: extensively used by Flux and Flagger projects, comprehensive CI/CD pipelines (.github/workflows/ has cve-scan.yml, e2e.yml, release.yml, test.yml), container image signing with cosign, SBOM generation, and multi-architecture support via Docker buildx. Active maintenance with modern Go 1.26.0 and recent dependency versions.

Very low risk: single maintainer (Stefan Prodan) but backed by CNCF ecosystem adoption; dependency surface is moderate (~30 direct deps) with well-maintained libraries (gorilla/mux, prometheus/client_golang, opentelemetry, uber-go/zap). No obvious breaking changes expected given its role as a reference implementation. Primary risk is that security/observability best practices it demonstrates may drift from upstream CNCF guidance.

Active development with recent Go 1.26.0 upgrade, OpenTelemetry instrumentation refinements across bridges/propagators, and hardened container image supply chain via Sigstore cosign signing and SLSA provenance attestation. CVE scanning integrated into CI pipeline.

git clone https://github.com/stefanprodan/podinfo.git && cd podinfo && make build && ./bin/podinfo (see Makefile for targets). For Docker: docker build -t podinfo . or use Dockerfile.xx for multi-arch.

Daily commands: make build to compile, then ./bin/podinfo --port=9898 (default). For development: make test runs unit tests, make fmt formats code. Docker: docker build -t podinfo:latest . then docker run -p 9898:9898 podinfo:latest. For Kubernetes: helm install podinfo ./charts/podinfo or kubectl apply -k kustomize/

• cmd/podinfo/main.go — Application entry point; initializes HTTP server, health checks, graceful shutdown, and signal handling—essential for understanding the bootstrap flow.
• Dockerfile — Multi-stage Docker build defining the container image; critical for production deployments and understanding the artifact pipeline.
• charts/podinfo/Chart.yaml — Helm chart metadata and versioning; primary distribution mechanism for Kubernetes deployments used by Flux and Flagger.
• charts/podinfo/templates/deployment.yaml — Core Kubernetes Deployment resource template; defines pod spec, health probes, resource limits, and instrumentation configuration.
• Makefile — Build orchestration, testing, and release automation; documents the development workflow and CI/CD pipeline conventions.
• .github/workflows/release.yml — Release automation including image builds, signing (Cosign/Notation), and multi-architecture support; critical for understanding artifact provenance.
• go.mod — Dependency manifest; lists OpenTelemetry instrumentation, Prometheus metrics, and security libraries that define the runtime behavior.

Add a new REST API endpoint

1. Define the handler function in pkg/http/handlers.go following the existing pattern (e.g., handleInfo, handleHealth) (pkg/http/handlers.go)
2. Register the route in cmd/podinfo/main.go by calling router.HandleFunc(path, handler) in the setupRoutes() section (cmd/podinfo/main.go)
3. Add Prometheus metrics in pkg/metrics/metrics.go to track requests/latency for the new endpoint (pkg/metrics/metrics.go)
4. Update the Helm chart values in charts/podinfo/values.yaml if the endpoint needs configuration flags (charts/podinfo/values.yaml)
5. Document the endpoint in README.md and add an e2e test in charts/podinfo/templates/tests/ if integration testing is needed (README.md)

Deploy podinfo to a new environment

1. Create a new overlay directory under deploy/overlays/{environment}/ (e.g., deploy/overlays/staging) (deploy/overlays/staging/kustomization.yaml)
2. Create a kustomization.yaml in the overlay specifying bases (backend, cache, frontend) and environment-specific patches (deploy/overlays/staging/kustomization.yaml)
3. Add namespace and label customizations via patches or files (e.g., labels.yaml, namespace.yaml) (deploy/overlays/staging/labels.yaml)
4. Deploy using kubectl apply -k deploy/overlays/{environment}/ or via Flux CD using a Kustomization resource (deploy/overlays/staging/kustomization.yaml)
5. Verify health checks and metrics by port-forwarding to the service and checking /healthz, /metrics endpoints (charts/podinfo/templates/deployment.yaml)

Configure Redis caching integration

1. Enable Redis in Helm values by setting cache.enabled=true in charts/podinfo/values.yaml (charts/podinfo/values.yaml)
2. Configure Redis connection details (host, port, TTL) via Helm value overrides or command-line flags (charts/podinfo/values.yaml)
3. Verify the Redis service is deployed using the Redis Deployment template at charts/podinfo/templates/redis/deployment.yaml (charts/podinfo/templates/redis/deployment.yaml)
4. Call cache operations (Get/Set) in handlers via the pkg/cache/cache.go client (pkg/cache/cache.go)
5. Monitor cache hit/miss metrics exposed by pkg/metrics/metrics.go via the /metrics endpoint (pkg/metrics/metrics.go)

Enable file watching for dynamic config reloading

1. Start the file watcher in cmd/podinfo/main.go by calling pkg/file/watcher.Watch() with the target directory (cmd/podinfo/main.go)
2. Mount ConfigMaps or Secrets as volumes in the Deployment template (charts/podinfo/templates/deployment.yaml) (charts/podinfo/templates/deployment.yaml)
3. Implement event handlers in pkg/file/watcher.go to reload configuration when files change (pkg/file/watcher.go)
4. Test the watcher by updating a ConfigMap and verifying the application picks up changes without restarting (pkg/file/watcher.go)

• Go — Fast startup, small binary footprint, and excellent Kubernetes ecosystem support via standard libraries and tooling.
• Prometheus + OpenTelemetry — Industry-standard observability stack for Kubernetes; enables metrics collection, distributed tracing, and integration with Flux/Flagger validation.
• Redis — Optional in-memory cache for demonstrating stateful services and cache invalidation patterns in Kubernetes.
• Helm — Kubernetes package manager; allows templated deployments across dev/staging/production with value overrides.
• Kustomize — Overlay-based configuration management; enables environment-specific patches without templating language overhead.
• Cosign + Notation — Container image signing and verification; demonstrates supply chain security best practices for production artifacts.

• Single monolithic binary vs. microservices

  • Why: Simplicity and fast deployment for a template project; easier for learning Kubernetes patterns.
  • Consequence: Limited demonstration of inter-service communication and service discovery; scales vertically rather than horizontally across services.

• Optional Redis dependency (not required)

  • Why: Showcases caching without forcing complexity; allows users to run podinfo without external storage.
  • Consequence: Cache data is ephemeral; users must implement persistence if needed.

• File watcher for ConfigMap/Secret updates

  • Why: Avoids pod restarts for configuration changes; demonstrates dynamic reload patterns.
  • Consequence: Complexity in state management; potential race conditions if multiple files change concurrently.

• Helm as primary distribution mechanism

  • Why: Standard for production Kubernetes; familiar to operators and integrates with Flux CD.
  • Consequence: Requires Helm CLI or compatible controllers; steeper learning curve than plain YAML.

• Not a production-grade application framework; exists purely as a template for teaching and testing.
• Does not implement authentication or authorization; suitable only for internal dev/test networks.
• Not a persistent data store; caching and logging are ephemeral unless external storage is configured.
• Not optimized for high throughput; designed for demonstrating patterns rather than performance benchmarks.

OpenTelemetry exporters require active OTLP gRPC collectors running at OTEL_EXPORTER_OTLP_ENDPOINT (default localhost:4317) or startup will hang waiting for connection. Redis cache is optional but /cache endpoints will fail if redis-addr config points to unavailable server. JWT tokens are hardcoded as 1-minute expiry (pkg/handlers/token.go). Helm chart expects container image in format podinfo:VERSION which requires building and pushing before helm install. Graceful shutdown waits up to the termination grace period (default 30s in k8s) before force-killing.

• Graceful Shutdown with SIGTERM/SIGINT handlers — Critical for Kubernetes reliability: allows in-flight requests to complete before process termination, preventing connection errors during rolling updates; implemented in cmd/podinfo/main.go with context cancellation
• Liveness vs Readiness Probes (Kubernetes health checks) — Podinfo exposes /healthz (liveness) and /readyz (readiness) separately; readiness can be toggled via POST endpoints to drain traffic without restarting, essential for zero-downtime deployments
• 12-Factor App methodology — Podinfo implements factor III (configuration via environment variables with viper) and factor IX (disposability with graceful shutdown), demonstrating portable microservice patterns across environments
• OpenTelemetry (OTEL) distributed tracing — Podinfo instruments HTTP handlers and gRPC calls with OTEL SDKs, exporting traces/logs/metrics to OTLP collectors; essential for observing microservice interactions across Kubernetes clusters
• Sigstore cosign container image signing — Podinfo's release pipeline (release.yml) signs container images with cosign and embeds SLSA provenance; enables keyless identity-based verification preventing supply chain attacks
• Fault Injection (chaos engineering) — Podinfo's /panic endpoint and random error/latency injection flags (--fault-delay, --fault-error) let teams test observability and resilience patterns under failure conditions
• Multi-architecture container builds (Docker buildx) — Release pipeline uses buildx to build amd64, arm64, and arm/v7 images simultaneously; critical for Kubernetes clusters running on heterogeneous hardware (Raspberry Pi to servers)

• fluxcd/flux2 — Primary consumer of podinfo for end-to-end testing of GitOps deployments and image updates via automated workflows
• fluxcd/flagger — Uses podinfo as test fixture for progressive delivery and canary deployment validation with automated traffic shifting
• kubernetes/examples — Shares similar goal of demonstrating Kubernetes-native application patterns (health checks, graceful shutdown, config management)
• sigstore/cosign — Podinfo demonstrates cosign container image signing and verification (.cosign/ directory with public key and signing workflows)
• prometheus/client_golang — Podinfo heavily instruments metrics export using this library at /metrics endpoint for Prometheus scraping

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for gRPC endpoints in e2e workflow

The repo has gRPC support (google.golang.org/grpc v1.79.3 dependency, grpcroute.yaml template, and cmd/podcli/ws.go suggesting gRPC capabilities), but the e2e.yml workflow only references HTTP-based tests. The charts/podinfo/templates/tests/grpc.yaml test template exists but lacks corresponding e2e validation. Adding gRPC endpoint integration tests would ensure the gRPC API contract is maintained across releases.

• [ ] Review .github/workflows/e2e.yml to understand current test structure
• [ ] Examine charts/podinfo/templates/tests/grpc.yaml to understand the test setup
• [ ] Create gRPC client tests in cmd/podcli or a new test package
• [ ] Add gRPC endpoint validation step to e2e.yml workflow
• [ ] Document gRPC testing procedure in deploy/README.md

Add OpenTelemetry instrumentation tests and validation

The repo has extensive OpenTelemetry dependencies (go.opentelemetry.io packages for traces, logs, and multiple propagators), but there are no visible test files validating trace export, metric collection, or propagator functionality. Adding tests would ensure observability features work correctly and prevent regressions in tracing/logging setup.

• [ ] Create cmd/podinfo/internal/telemetry_test.go to test trace exporter initialization
• [ ] Add tests for each propagator (AWS, B3, Jaeger, OT) in internal/otel/propagators_test.go
• [ ] Create integration test validating end-to-end trace collection in test.yml workflow
• [ ] Add test case in charts/podinfo/templates/tests/ for observability validation
• [ ] Document telemetry configuration testing in README.md

Add code signing verification tests and documentation

The repo has Cosign (.cosign/ directory with cosign.pub) and Notation (.notation/ directory with trustpolicy.json and signing certificates) configuration for artifact signing, but there are no tests or documentation validating signature verification workflows. Adding tests would ensure the signing/verification pipeline is functional and prevent supply chain security regressions.

• [ ] Create .github/workflows/verify-signatures.yml to test Cosign verification of container images
• [ ] Add step to validate Notation signature verification in release.yml workflow
• [ ] Create Makefile target (e.g., 'make verify-signatures') for local signature validation
• [ ] Document signature verification process in .cosign/README.md and .notation/README.md with examples
• [ ] Add test cases validating both unsigned and signed artifacts fail appropriately

• Add integration tests for the gRPC echo service (grpc/ directory exists but tests/ lacks gRPC client test coverage); requires learning protobuf and grpc-go client patterns used in Go
• Implement /cache/{key} endpoint pagination or listing (currently only supports individual key operations); requires modifying Redis query logic in pkg/handlers/cache.go and adding new HTTP routes
• Create Kustomize overlays for common deployment scenarios (staging, prod with HPA, dev with mocks); requires understanding charts/podinfo template structure and kustomize patch patterns

• High · Outdated Go Version — go.mod (go 1.26.0). The project specifies Go 1.26.0 in go.mod, which is a future/unreleased version. This appears to be a configuration error. Using non-standard or future versions can lead to dependency resolution issues and security patches not being applied correctly. Fix: Use a stable, currently supported Go version (e.g., 1.22 or 1.23). Verify the correct version and update go.mod accordingly.
• Medium · Sensitive Files Stored in Repository — .cosign/cosign.pub, .notation/notation.crt, .notation/signingkeys.json, .notation/trustpolicy.json. The repository contains sensitive security-related files in version control: .cosign/cosign.pub, .notation/notation.crt, .notation/signingkeys.json, and .notation/trustpolicy.json. While public keys are less critical, private signing keys and configuration should not be committed. Fix: Move sensitive keys and certificates to secure secret management systems (e.g., HashiCorp Vault, AWS Secrets Manager). Commit only public keys if necessary, and rotate any exposed credentials immediately.
• Medium · Potential Hardcoded Credentials in Signing Configuration — .notation/codesign.cnf. The .notation/codesign.cnf file may contain sensitive configuration for code signing. If this includes credentials or sensitive paths, it should not be stored in the repository. Fix: Review the file contents. Move any credentials to environment variables or secret management systems. Use environment variable substitution in configuration files.
• Medium · Missing Security Headers Configuration — cmd/podinfo/main.go and HTTP handler implementations. Based on the file structure showing a Go microservice with web endpoints, there is no visible configuration for security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in the provided code snippets. Fix: Implement security headers middleware in the HTTP handlers. Add Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and other relevant headers to all responses.
• Medium · Permissive User Permissions in Docker Image — Dockerfile (chown -R app:app ./). While the Dockerfile creates a non-root 'app' user, the file ownership is set recursively with chown -R, and the /home/app directory is world-readable by default in Alpine. This could allow information disclosure. Fix: Set explicit restrictive permissions: 'RUN chmod -R 750 /home/app' after chown. Review and restrict file permissions to only what the application needs.
• Low · Potential Race Condition in File Operations — Dockerfile (COPY --from=builder and RUN chown -R). The Dockerfile copies files from builder and then changes ownership. Between COPY and chown, files are owned by root, which could theoretically be a race condition in concurrent environments. Fix: Consider using --chown flag in COPY commands: 'COPY --chown=app:app --from=builder /podinfo/bin/podinfo .' to atomically set ownership.
• Low · Dependency Version Pinning Incomplete — go.mod (all dependencies). The go.mod file uses exact versions for most dependencies, but indirect dependencies may not be fully controlled. Some dependencies like protobuf and grpc are at high major versions which could introduce breaking changes. Fix: Regularly run 'go mod audit' and 'go list -u -m all' to check for security updates. Consider using 'go mod tidy' and maintaining a go.sum file lock for reproducible builds.
• Low · Missing SBOM and Supply Chain Security — .github/workflows and Makefile. While the project has cosign and notation configuration for signing, there's no visible Software Bill of Materials (SBOM) generation documented in the build pipeline, which limits supply chain transparency. Fix: Integrate SBOM generation tools (syft, cyclonedx) into CI/CD pipeline. Generate and publish SBOMs alongside releases for transparency.
• Low · Potential Missing — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.