test: add Doc Detective coverage for the Kind local development guide - #1851
test: add Doc Detective coverage for the Kind local development guide#1851JakeSCahill wants to merge 1 commit into
Conversation
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughAdds conditional Kind-guide detection and a dedicated GitHub Actions job running Doc Detective. The guide now embeds automated commands covering Kind setup, prerequisite checks, operator and Redpanda deployment, topic and message operations, Console validation, Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant GitHubActions
participant DocDetective
participant Kind
participant Kubernetes
participant RedpandaOperator
GitHubActions->>DocDetective: Run Kind guide test
DocDetective->>Kind: Create test cluster
DocDetective->>Kubernetes: Install resources and apply manifests
Kubernetes->>RedpandaOperator: Deploy operator
RedpandaOperator-->>Kubernetes: Report readiness
Kubernetes-->>DocDetective: Return validation results
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/workflows/test-docs.yml (1)
12-17: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick winRestrict workflow permissions.
setuphas no explicit permissions block, whiletest-kind-guidegrantscontents: writeandpull-requests: writealthough it only reads code and creates issues. Use least-privilege permissions:contents: readfor setup, and onlycontents: read,issues: write, andid-token: writefor the test job.Also applies to: 113-117
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/test-docs.yml around lines 12 - 17, Update the workflow permissions for the setup job to explicitly grant only contents: read. Change the test-kind-guide job permissions to contents: read, issues: write, and id-token: write, removing the unnecessary pull-requests: write and any other broader access.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/test-docs.yml:
- Around line 118-119: Increase the timeout-minutes value for the workflow job
using runs-on ubuntu-latest so it accommodates the documented Redpanda
readiness, broker deletion, installation waits, and teardown budgets without
premature cancellation.
- Around line 121-133: Restrict the run-tests and test-kind-guide jobs to
unprivileged Doc Detective execution: remove AWS credential setup, Secrets
Manager token retrieval, and authenticated checkout, configure actions/checkout
with no token and persist-credentials disabled, and avoid installing
PR-controlled dependencies with secrets or write access. Move any issue creation
into a separate trusted job that runs only after these tests and retains the
required permissions and credentials.
- Around line 30-33: Update the kindguide path filter in the test-docs workflow
to include the rpk installation partial referenced by local-guide.adoc, ensuring
changes to that partial trigger test-kind-guide alongside the existing guide,
Kubernetes partial, and antora.yml paths.
In `@modules/deploy/pages/redpanda/kubernetes/local-guide.adoc`:
- Around line 516-518: Remove the unnecessary envsubst stage from the kubectl
command in the local guide, including its corresponding step command
representation, while preserving the Go-template rendering and tee output
unchanged.
- Around line 503-507: Update the port-forward test steps around the runShell
command to wait for readiness with bounded polling of the localhost endpoint or
port-forward log instead of a fixed sleep. Preserve the existing HTTP status
check, and make cleanup of the PID from port-forward.pid idempotent by
tolerating an already-exited process.
- Around line 346-348: Replace the fixed 10-second sleep before the operator log
check with a bounded polling step that repeatedly queries the operator logs
until they contain “twitch-chat” or the timeout is reached. Keep the existing
kubectl log command, namespace, container, and twitch-chat output behavior, and
ensure the poll fails only after the bounded retry window expires.
- Around line 542-543: Update the rpk installation and related test steps in the
local guide, including the steps at the referenced locations, to use
$HOME/.local/bin rather than a quoted ~/ path. Ensure later bare rpk invocations
can resolve the installed binary by invoking it through $HOME/.local/bin or
explicitly prepending that directory to PATH in each affected step.
- Around line 424-425: Update the expanded kubectl exec commands in the test
steps at the referenced locations to remove TTY allocation by deleting -t.
Retain -i only for the producer write path where stdin is required, and remove
it from non-interactive commands such as the topic description step.
---
Outside diff comments:
In @.github/workflows/test-docs.yml:
- Around line 12-17: Update the workflow permissions for the setup job to
explicitly grant only contents: read. Change the test-kind-guide job permissions
to contents: read, issues: write, and id-token: write, removing the unnecessary
pull-requests: write and any other broader access.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 60e23c72-83b4-4968-8edc-203434340723
📒 Files selected for processing (4)
.github/workflows/test-docs.ymlmodules/deploy/pages/redpanda/kubernetes/local-guide.adocmodules/deploy/partials/kubernetes/deploy-operator.adoctests/setup-tests/.doc-detective.json
| kindguide: | ||
| - 'modules/deploy/pages/redpanda/kubernetes/local-guide.adoc' | ||
| - 'modules/deploy/partials/kubernetes/**' | ||
| - 'antora.yml' |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Include the rpk installation partial in this filter.
local-guide.adoc includes get-started:partial$install-rpk-linux.adoc at Line 540, but this filter only watches the local guide, Kubernetes partials, and antora.yml. Changes to the rpk installation instructions can therefore break the guide without running test-kind-guide.
Suggested filter update
kindguide:
- 'modules/deploy/pages/redpanda/kubernetes/local-guide.adoc'
- 'modules/deploy/partials/kubernetes/**'
+ - 'modules/get-started/partials/install-rpk-linux.adoc'
- 'antora.yml'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| kindguide: | |
| - 'modules/deploy/pages/redpanda/kubernetes/local-guide.adoc' | |
| - 'modules/deploy/partials/kubernetes/**' | |
| - 'antora.yml' | |
| kindguide: | |
| - 'modules/deploy/pages/redpanda/kubernetes/local-guide.adoc' | |
| - 'modules/deploy/partials/kubernetes/**' | |
| - 'modules/get-started/partials/install-rpk-linux.adoc' | |
| - 'antora.yml' |
🧰 Tools
🪛 zizmor (1.28.0)
[warning] 12-33: overly broad permissions (excessive-permissions): default permissions used due to no permissions: block
(excessive-permissions)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/test-docs.yml around lines 30 - 33, Update the kindguide
path filter in the test-docs workflow to include the rpk installation partial
referenced by local-guide.adoc, ensuring changes to that partial trigger
test-kind-guide alongside the existing guide, Kubernetes partial, and antora.yml
paths.
| runs-on: ubuntu-latest | ||
| timeout-minutes: 45 |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Increase the job timeout.
The guide permits 21 minutes for Redpanda readiness, 11 minutes for broker deletion, and additional 5-minute installation waits plus teardown. A healthy but slow run can exceed 45 minutes and be killed before cleanup. Increase the job timeout or reduce the individual budgets.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/test-docs.yml around lines 118 - 119, Increase the
timeout-minutes value for the workflow job using runs-on ubuntu-latest so it
accommodates the documented Redpanda readiness, broker deletion, installation
waits, and teardown budgets without premature cancellation.
| - uses: aws-actions/configure-aws-credentials@v4 | ||
| with: | ||
| aws-region: ${{ vars.RP_AWS_CRED_REGION }} | ||
| role-to-assume: arn:aws:iam::${{ secrets.RP_AWS_CRED_ACCOUNT_ID }}:role/${{ vars.RP_AWS_CRED_BASE_ROLE_NAME }}${{ github.event.repository.name }} | ||
| - uses: aws-actions/aws-secretsmanager-get-secrets@v2 | ||
| with: | ||
| secret-ids: | | ||
| ,sdlc/prod/github/actions_bot_token | ||
| parse-json-secrets: true | ||
| - uses: actions/checkout@v4 | ||
| with: | ||
| token: ${{ env.ACTIONS_BOT_TOKEN }} | ||
| path: redpanda-docs |
There was a problem hiding this comment.
🔒 Security & Privacy | 🔴 Critical | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
rg -n -C2 'configure-aws-credentials|aws-secretsmanager|GITHUB_ENV|persist-credentials' \
.github/workflows/test-docs.ymlRepository: redpanda-data/docs
Length of output: 1427
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo "== workflow size =="
wc -l .github/workflows/test-docs.yml
echo "== relevant sections =="
sed -n '1,190p' .github/workflows/test-docs.yml | cat -n
echo "== commands/runs in workflow =="
rg -n '(^ *(run|environment):\s*|^\s+- name:|configure-aws-credentials|aws-secretsmanager|GITHUB_ENV|persist-credentials|chmod|npm install|run:)' .github/workflows/test-docs.ymlRepository: redpanda-data/docs
Length of output: 9059
🌐 Web query:
aws-actions/aws-secretsmanager-get-secrets @v2 secret environment variables documentation
💡 Result:
The aws-actions/aws-secretsmanager-get-secrets @v2 action allows you to retrieve secrets from AWS Secrets Manager and inject them into your GitHub Actions workflow as environment variables [1][2][3]. Key behavior and configuration options for environment variables include: Default Naming Behavior By default, the action generates environment variable names based on the secret name [1][2]. These names are automatically transformed to contain only uppercase letters, numbers, and underscores, and are ensured not to begin with a number [1][2]. Custom Naming You can define a custom environment variable name by specifying it before the secret ID, separated by a comma (e.g., ENV_VAR_NAME, secretId) [1][2]. Custom names must consist only of uppercase letters, numbers, and underscores [1][2]. Name Transformation The name-transformation input allows you to control the case of the generated environment variable names [1][2]. - uppercase (default): Transforms names to uppercase [1][2]. - lowercase: Transforms names to lowercase [1][2]. - none: Keeps the name as provided (or as it appears in the secret name, subject to valid naming constraints) [2]. JSON Secrets - By default (parse-json-secrets: false), the entire JSON string of the secret value is set as the environment variable value [1][2]. - When set to true (parse-json-secrets: true), the action parses the JSON and creates individual environment variables for each key-value pair found in the secret [1][2]. Note that if the JSON contains case-sensitive keys that would result in duplicate environment variable names (e.g., "name" and "Name"), this may cause conflicts [2]. Usage Example - name: Get Secrets uses: aws-actions/aws-secretsmanager-get-secrets@v2 with: secret-ids: | secretId1 MY_CUSTOM_VAR, secretId2 parse-json-secrets: true name-transformation: uppercase The action also supports using prefixes (e.g., dev*) to retrieve multiple secrets at once, provided you do not explicitly assign a custom variable name for those matched secrets [1][2].
Citations:
- 1: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/README.md
- 2: https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets_github.html
- 3: https://github.com/aws-actions/aws-secretsmanager-get-secrets/
🌐 Web query:
github-actions checkout persist-credentials default true README
💡 Result:
In the GitHub Actions checkout action (actions/checkout), the persist-credentials input parameter controls whether the GitHub token or SSH key used for the repository checkout is configured in the local git configuration [1][2][3]. Key details regarding this parameter include: Default Value: The default is true [1][2][3]. Function: When set to true (default), the credentials are made available to the local git configuration [4][5]. This allows subsequent steps in your workflow job to execute authenticated git commands (such as git fetch or git push) without requiring additional setup [4][2][5]. Security Note: Because the credentials are stored in the git configuration, they are technically accessible to other steps in the same job [6]. The action automatically cleans up these credentials during the post-job phase [4][7]. Opt-out: To disable this behavior for security reasons or if you do not require authenticated git commands in later steps, you can explicitly set persist-credentials: false in your workflow step [4][2][6]. Recent Improvements: In recent versions (such as v6.0.2), credential storage has been improved to store these credentials in a separate file under $RUNNER_TEMP rather than directly within the.git/config file, enhancing security while maintaining existing functionality [5].
Citations:
- 1: https://github.com/actions/checkout/blob/main/action.yml
- 2: https://github.com/actions/checkout/tree/v6.0.2?tab=readme-ov-file
- 3: https://github.com/actions/checkout/blob/72f2cec99f417b1a1c5e2e88945068983b7965f9/action.yml
- 4: https://github.com/marketplace/actions/checkout
- 5: https://github.com/actions/checkout/tree/v6.0.2
- 6: Remove
persist-credentialsor change the default tofalseactions/checkout#485 - 7: https://github.com/marketplace/actions/checkout?version=v3.6.0
Do not expose AWS and write permissions to Doc Detective commands.
Both run-tests and test-kind-guide provision AWS credentials, fetch the actions bot token, checkout with that token, install PR-controlled dependencies, and then invoke Doc Detective; the token is also written to GITHUB_ENV and checkout does not opt out of persisted credentials. Run checkout, npm install, and Doc Detective without secrets/write permissions, checkout with persist-credentials: false using no auth, and move issue creation to a separate trusted job.
🧰 Tools
🪛 zizmor (1.28.0)
[warning] 130-133: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false
(artipacked)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/test-docs.yml around lines 121 - 133, Restrict the
run-tests and test-kind-guide jobs to unprivileged Doc Detective execution:
remove AWS credential setup, Secrets Manager token retrieval, and authenticated
checkout, configure actions/checkout with no token and persist-credentials
disabled, and avoid installing PR-controlled dependencies with secrets or write
access. Move any issue creation into a separate trusted job that runs only after
these tests and retains the required permissions and credentials.
Source: Linters/SAST tools
| // Give the Redpanda Operator a few seconds to reconcile the Topic resource before checking the logs. | ||
| // (step {"runShell": {"command": "sleep 10", "timeout": 30000, "exitCodes": [0]}}) | ||
| // (step {"runShell": {"command": "kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace redpanda", "timeout": 60000, "exitCodes": [0], "stdio": "twitch-chat"}}) |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Replace the fixed topic-reconciliation sleep with a bounded poll.
Ten seconds is not a readiness guarantee. On a slow runner, the operator logs may not contain twitch-chat yet, causing a false failure even though reconciliation succeeds shortly afterward.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@modules/deploy/pages/redpanda/kubernetes/local-guide.adoc` around lines 346 -
348, Replace the fixed 10-second sleep before the operator log check with a
bounded polling step that repeatedly queries the operator logs until they
contain “twitch-chat” or the timeout is reached. Keep the existing kubectl log
command, namespace, container, and twitch-chat output behavior, and ensure the
poll fails only after the bounded retry window expires.
| // The test runs the expanded form of the internal-rpk alias because each test step runs in a new shell, where aliases don't persist. | ||
| // (step {"runShell": {"command": "kubectl --namespace redpanda exec -i -t redpanda-0 -c redpanda -- rpk topic describe twitch-chat", "timeout": 60000, "exitCodes": [0], "stdio": "twitch-chat"}}) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
matches="$(rg -n 'kubectl .*exec .* -i -t' \
modules/deploy/pages/redpanda/kubernetes/local-guide.adoc |
rg 'topic (describe|produce|consume)' || true)"
test -z "$matches"Repository: redpanda-data/docs
Length of output: 156
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
file="modules/deploy/pages/redpanda/kubernetes/local-guide.adoc"
printf '--- relevant kubectl exec lines ---\n'
rg -n 'kubectl .*exec|topic (describe|produce|consume)' "$file" | sed -n '1,160p'
printf '\n--- file excerpt around referenced lines ---\n'
sed -n '400,490p' "$file"
printf '\n--- any -t in kubectl exec lines ---\n'
python3 - <<'PY'
from pathlib import Path
p = Path('modules/deploy/pages/redpanda/kubernetes/local-guide.adoc')
for i, line in enumerate(p.read_text().splitlines(), 1):
if 'kubectl' in line and 'exec' in line and '-t' in line:
print(f'{i}: {line}')
PYRepository: redpanda-data/docs
Length of output: 247
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
file="modules/deploy/pages/redpanda/kubernetes/local-guide.adoc"
printf '%s\n' '--- relevant kubectl exec lines ---'
rg -n 'kubectl .*exec|topic (describe|produce|consume)' "$file" | sed -n '1,160p'
printf '%s\n' '--- file excerpt around referenced lines ---'
sed -n '400,490p' "$file"
printf '%s\n' '--- any -t in kubectl exec lines ---'
python3 - <<'PY'
from pathlib import Path
p = Path('modules/deploy/pages/redpanda/kubernetes/local-guide.adoc')
for i, line in enumerate(p.read_text().splitlines(), 1):
if 'kubectl' in line and 'exec' in line and '-t' in line:
print(f'{i}: {line}')
PYRepository: redpanda-data/docs
Length of output: 4628
Remove TTY allocation from automated kubectl exec commands.
These test steps run non-interactively, so -t is unnecessary and only keep -i where stdin is required (the producer write path). Apply this to the expanded kubectl. commands at lines 425, 473, and 482.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@modules/deploy/pages/redpanda/kubernetes/local-guide.adoc` around lines 424 -
425, Update the expanded kubectl exec commands in the test steps at the
referenced locations to remove TTY allocation by deleting -t. Retain -i only for
the producer write path where stdin is required, and remove it from
non-interactive commands such as the topic description step.
Source: MCP tools
| // The explore-topics-localhost partial documents port-forwarding plus browser steps. The test runs the documented port-forward in the background and verifies Redpanda Console with an HTTP status check instead of browser steps, because shell checks are more stable than a browser session inside a cluster test. | ||
| // (step {"runShell": {"command": "nohup kubectl --namespace redpanda port-forward svc/redpanda-console 8080:8080 >port-forward.log 2>&1 & echo $! > port-forward.pid\nsleep 5", "workingDirectory": "./kind-guide", "timeout": 30000, "exitCodes": [0]}}) | ||
| // (step {"httpRequest": {"url": "http://localhost:8080", "method": "get", "statusCodes": [200], "timeout": 30000}}) | ||
| // Stop the documented port-forward process (the docs use Ctrl+C). | ||
| // (step {"runShell": {"command": "kill $(cat port-forward.pid)", "workingDirectory": "./kind-guide", "timeout": 30000, "exitCodes": [0]}}) |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Wait for port-forward readiness before making the HTTP request.
sleep 5 can race with service startup, causing a transient connection failure. Poll the endpoint or port-forward log with a bounded timeout, and make process cleanup idempotent (kill ... || true) if the process has already exited.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@modules/deploy/pages/redpanda/kubernetes/local-guide.adoc` around lines 503 -
507, Update the port-forward test steps around the runShell command to wait for
readiness with bounded polling of the localhost endpoint or port-forward log
instead of a fixed sleep. Preserve the existing HTTP status check, and make
cleanup of the PID from port-forward.pid idempotent by tolerating an
already-exited process.
| sudo true && kubectl --namespace <namespace> get endpoints,node -A -o go-template='{{ range $_ := .items }}{{ if and (eq .kind "Endpoints") (eq .metadata.name "redpanda-external") }}{{ range $_ := (index .subsets 0).addresses }}{{ $nodeName := .nodeName }}{{ $podName := .targetRef.name }}{{ range $node := $.items }}{{ if and (eq .kind "Node") (eq .metadata.name $nodeName) }}{{ range $_ := .status.addresses }}{{ if eq .type "InternalIP" }}{{ .address }} {{ $podName }}.customredpandadomain.local{{ "\n" }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}' | envsubst | sudo tee -a /etc/hosts | ||
| ``` | ||
| // (step {"runShell": {"command": "sudo true && kubectl --namespace redpanda get endpoints,node -A -o go-template='{{ range $_ := .items }}{{ if and (eq .kind \"Endpoints\") (eq .metadata.name \"redpanda-external\") }}{{ range $_ := (index .subsets 0).addresses }}{{ $nodeName := .nodeName }}{{ $podName := .targetRef.name }}{{ range $node := $.items }}{{ if and (eq .kind \"Node\") (eq .metadata.name $nodeName) }}{{ range $_ := .status.addresses }}{{ if eq .type \"InternalIP\" }}{{ .address }} {{ $podName }}.customredpandadomain.local{{ \"\\n\" }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}' | envsubst | sudo tee -a /etc/hosts", "timeout": 60000, "exitCodes": [0], "stdio": "redpanda-0.customredpandadomain.local"}}) |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
Remove the unnecessary envsubst dependency.
kubectl renders the Go template before the pipe, so envsubst has no variables left to substitute. It adds an undeclared gettext dependency to the Linux-only instructions; remove it or document/install the required package.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@modules/deploy/pages/redpanda/kubernetes/local-guide.adoc` around lines 516 -
518, Remove the unnecessary envsubst stage from the kubectl command in the local
guide, including its corresponding step command representation, while preserving
the Go-template rendering and tee output unchanged.
| // The test adds -o to unzip so that the step is non-interactive when rpk is already installed in the test environment. CI runners are amd64. | ||
| // (step {"runShell": {"command": "curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH=\"~/.local/bin:$PATH\" && unzip -o rpk-linux-amd64.zip -d ~/.local/bin/", "workingDirectory": "./kind-guide", "timeout": 180000, "exitCodes": [0]}}) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
actual="$(bash -c 'export PATH="~/.local/bin:$PATH"; printf "%s" "$PATH"')"
[[ "$actual" == "~/.local/bin:"* ]]Repository: redpanda-data/docs
Length of output: 156
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="modules/deploy/pages/redpanda/kubernetes/local-guide.adoc"
if [ -f "$file" ]; then
echo "=== file exists: $file ($(wc -l < "$file") lines) ==="
echo "=== relevant sections ==="
sed -n '520,570p' "$file" | cat -n
echo "=== section 600-620 ==="
sed -n '595,625p' "$file" | cat -n
echo "=== rpk usages in file ==="
rg -n '\brpk\b' "$file" || true
else
echo "file not found: $file"
fd -a 'local-guide.adoc' .
fiRepository: redpanda-data/docs
Length of output: 8293
Make the rpk binary available to later steps.
In quoted strings, ~ remains literal, so ~/.local/bin is not expanded and the exported PATH applies only for that installation command. Later steps invoke bare rpk, so a clean local runner can fail with command not found. Use $HOME/.local/bin and invoke the binary explicitly, or prepend that directory in each later step.
Also applies to the test steps at lines 543, 553, 560, and 610.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@modules/deploy/pages/redpanda/kubernetes/local-guide.adoc` around lines 542 -
543, Update the rpk installation and related test steps in the local guide,
including the steps at the referenced locations, to use $HOME/.local/bin rather
than a quoted ~/ path. Ensure later bare rpk invocations can resolve the
installed binary by invoking it through $HOME/.local/bin or explicitly
prepending that directory to PATH in each affected step.
Source: MCP tools
|
Consolidated into #1846 per team preference — the test rides with the PR that fixes the issues it guards (commit |
1 participant
What this adds
End-to-end Doc Detective coverage for
modules/deploy/pages/redpanda/kubernetes/local-guide.adoc, following the same inline-comment pattern as the quickstart test, plus a dedicated CI job.What the test runs
One test (
testId: kind-guide, 44 steps) that follows the kind + Operator tab path exactly as a user would, withredpandasubstituted wherever the docs say<namespace>:kubectl,helm,kind,docker)kind.yamlas documented andkind create cluster(3 workers + control plane)kubectl auth can-i create CustomResourceDefinitionwith ayesoutput checkdeploy-operatorpartial), thenrollout status --watchredpanda-cluster.yamlwrite + apply, wait for the Redpanda resourceReadyconditiontwitch-chatreconcile evidencerpk topic describe/ pipedproduce/consume --num 1throughkubectl execwith output matches (Pandas are fabulous!)/etc/hostsmapping command (run verbatim, CI runners have passwordless sudo),ca.crtsave,rpkinstall,rpk profile createfrom theredpanda-rpkConfigMap, andrpk cluster infokind delete cluster, plus a defensivekind delete clusteropener for a clean slateDocs bugs this work caught (fixed in this PR)
/etc/hostscommand on the page: the inline go-template had 7 block opens (range/if) but only 5{{ end }}tokens, sokubectlrejects it withunexpected EOFfor every user. The sharedexternal-access-steps.adocpartial has the correct 7-endform. Fixed by adding the two missing{{ end }}tokens (verified against a live kind cluster: output matches the documentedIP redpanda-N.customredpandadomain.localshape).deploy-operator.adochardcodes:latest-operator-version: 25.2.0as a raw-file fallback, but chart25.2.0no longer exists in the Helm index (helm install --version 25.2.0fails). Production builds inject the real latest release (v26.2.1) at build time, so the rendered docs are fine. Updated the fallback tov26.2.1.Deliberate deviations from the literal docs commands (each noted with an inline comment in the page)
--watch:kubectl get redpanda --watchnever exits, so the test useskubectl wait redpanda/redpanda --for=condition=Ready --timeout=1200s(verified working against the v26.2.1 operator CRD), plus a broker-podReadywait because the Redpanda resource can report Ready while the last pod is still starting.internal-rpkalias: each test step runs in a new shell, so aliases don't persist. The test runs the fullkubectl --namespace redpanda exec -i -t redpanda-0 -c redpanda -- rpk ...form the alias documents. Piped produce matches the quickstart test's pattern.localhost:8080, because shell checks are more stable than a browser session inside a cluster test.Other small test-only accommodations:
unzip -oso the rpk install step is non-interactive when rpk already exists in the test environment, the operator chart version is resolved from the Helm index (mirrors the build-time-injected{latest-operator-version}instead of the raw-file fallback, which goes stale by design), and a bounded wait for broker-pod deletion during uninstall so PVC deletion isn't blocked by PVC protection (this teardown race is real: deleting the Redpanda resource returns before pods finish terminating — possible docs follow-up).rpk profile create --from-profile <(kubectl get configmap ...)runs verbatim: Doc Detective executesrunShellthroughbash -c, so process substitution works.Linux-only scoping
The test declares
"runOn": [{"platforms": ["linux"]}]in itstest startstatement (test-levelrunOnoverrides the config contexts per the Doc Detective schema). The external-access section is documented as Linux-only and CI runs ubuntu. On macOS the test is skipped cleanly (verified).Config change
The inline-statement regexes in
tests/setup-tests/.doc-detective.jsonchanged from lazy ((.*?)\)) to greedy ((.*)\)). The lazy form truncates any step containing a)character (the/etc/hostsgo-template command is full of them) and crashes resolution withInvalid JSON or YAML format. All 58 quickstart statements and the 7 console-auth statements parse identically under the greedy form (verified), since every statement is the only thing on its line.CI
New
test-kind-guidejob intest-docs.yml:kindguide: the guide page,modules/deploy/partials/kubernetes/**,antora.yml) on PRs, always on schedule/workflow_dispatch/repository_dispatchhelm/kind-action@v1(install_only: true)doc-detective/github-action@v1withexit_on_fail,create_issue_on_fail, issue title/labels, andintegrations: claudewith a targeted triage promptLocal smoke evidence (macOS, M-series, kind v0.32.0)
Ran every command manually end to end against a real 4-node kind cluster (committed test timeouts are calibrated at roughly 2-5x these timings):
kind create cluster(4 nodes)Readyafter applykind delete clusterThe only paths not fully verifiable on macOS are
/etc/hostswrites (ran the pipeline intocatinstead ofsudo tee, output shape verified) and externalrpk cluster info(kind node IPs are unreachable from the mac host — Linux-only by design, which is exactly why the test is Linux-scoped).Validation
Validation PASSED(44/44 steps)Note: the first full CI validation run should be triggered via
workflow_dispatchonce merge review starts.🤖 Generated with Claude Code