Spike: Keep Pod Log Output Current Using Automated Artifact Generation

[samayer12]

Description

Example documentation in pepr-excellent-examples may include pod log output snippets. Like code snippets (see #191), these logs can become outdated when the examples change. We should research automated solutions to keep pod logs current, potentially using GitHub Actions artifacts to share logs between repositories.

Current state:

• Pod log output (if included) is manually copied into documentation
• No automated verification that logs match current example behavior
• Logs can become stale as examples evolve

Problems:

• Manual maintenance - Developers must manually run examples and copy log output
• Documentation drift - Easy to forget to update logs when examples change
• No validation - No way to verify logs are accurate for current code
• Time-consuming - Running examples to capture logs is tedious

Proposed solution (requires research):

Option 1: GitHub Actions Artifacts (cross-repo)

1. Add workflow to pepr-excellent-examples that runs each example
2. Capture pod logs as artifacts
3. pepr-docs build downloads artifacts and extracts logs
4. Inject logs into documentation during build

Challenges:

• Cross-repository artifact access complexity
• Artifact retention limits (90 days default)
• Authentication/permissions between repos
• Timing coordination (when to generate artifacts)

Option 2: Commit logs to pepr-excellent-examples

1. GitHub Actions in pepr-excellent-examples runs examples
2. Captures logs and commits them to repo (e.g., logs/ directory)
3. pepr-docs reads logs during build like it reads READMEs
4. Simpler than artifacts, but adds noise to git history

Option 3: On-demand generation in pepr-docs

1. pepr-docs build process runs examples locally
2. Captures logs in real-time during build
3. No cross-repo complexity
4. Requires Kubernetes cluster access during build (problematic for CI/CD)

Option 4: Manual with validation

1. Keep logs in pepr-excellent-examples manually
2. Add CI check that validates logs match current output
3. Fails if logs are outdated
4. Less automated but simpler to implement

Related Files

• https://github.com/defenseunicorns/pepr-excellent-examples (external repository)
• https://github.com/defenseunicorns/pepr-docs/blob/main/scripts/index.mjs
• https://github.com/defenseunicorns/pepr-docs/blob/main/.github/workflows/docs.yml
• https://github.com/defenseunicorns/pepr-docs/blob/main/.github/workflows/test.yml

Definition of Done

We've considered our options and learned more about the problem. Perhaps we've even come up with an alternative idea!

Benefits (if implemented):

• Always current log output in documentation
• Reduced manual maintenance
• Confidence that examples work as documented
• Better user experience with accurate examples

Risks:

• High implementation complexity for potentially low value
• Cross-repo dependencies could make builds fragile
• Artifact retention limits could cause build failures
• May be over-engineering if logs rarely change