Skip to content

Docs: runbook update#345

Open
vertex451 wants to merge 5 commits intomainfrom
artem/runbook-update
Open

Docs: runbook update#345
vertex451 wants to merge 5 commits intomainfrom
artem/runbook-update

Conversation

@vertex451
Copy link
Contributor

Changes

updated local provider setup make commands

@coderabbitai
Copy link

coderabbitai bot commented Nov 7, 2025

Walkthrough

This pull request introduces comprehensive documentation for the Akash development environment across multiple runbook variants. It includes a new main README, an operations guide for Kubernetes deployments, and restructured setup guides for local Kind clusters, single-network configurations, and remote SSH cluster access.

Changes

Cohort / File(s) Summary
Documentation Framework
_run/README.md
New main documentation file providing overview of development environment structure, prerequisites, setup instructions, runbook directory layout, and pointers to specific runbook variants (kube, ssh).
Local Kind Cluster (kube)
_run/kube/README.md, _run/kube/OPERATIONS.md
Comprehensive restructuring of local Kind cluster runbook with 9-step sequence, multi-terminal workflow guidance, and troubleshooting notes. New OPERATIONS.md documents deployment updates, lease terminations, and mutable SDL fields.
SSH Cluster Configuration
_run/ssh/README.md
Complete redesign from local to remote SSH-based cluster access, including remote cluster setup steps, kubeconfig configuration, SSH key-based authentication, GPU support sections, and extended troubleshooting guidance.
Runbook Updates
_run/single/README.md
Minor updates to single-network configuration: terminal count adjustments, make target name updates (kind-cluster-* to kube-cluster-*), and clarification of standard vs. Calico network setup.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested reviewers

  • boz
  • troian
  • chainzero

Poem

A dev guide blooms in markdown light, 🐰
With Kind clusters spinning, SSH paths shining bright,
Nine careful steps and operations clear,
The runbook hops—deployment's engineering sphere!
From local to remote, troubleshooting and all,
This documentation answers each developer's call. 📚✨

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title 'Docs: runbook update' is related to the changeset and correctly identifies that this PR updates documentation for the runbooks, which is the primary focus of all changes.
Description check ✅ Passed The description 'updated local provider setup make commands' is related to the changeset, which includes updates to runbook documentation with new and modified make commands across multiple documentation files.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch artem/runbook-update

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@vertex451 vertex451 self-assigned this Jan 29, 2026
@vertex451 vertex451 marked this pull request as ready for review January 29, 2026 15:11
@vertex451 vertex451 requested a review from a team as a code owner January 29, 2026 15:11
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🤖 Fix all issues with AI agents
In `@_run/kube/OPERATIONS.md`:
- Around line 39-43: In the "Tenant closes the group" section (header "Tenant
closes the group") replace the duplicated command `make group-pause` with the
correct `make group-close` so the command matches the naming pattern used for
other close operations (e.g., `deployment-close`, `lease-close`, `bid-close`)
and the intended action; update the code block under that header to contain
`make group-close`.

In `@_run/kube/README.md`:
- Line 161: Fix the typo in the README line that reads "Take note of the
deplpyment ID (DSEQ) generated for use in subsequent steps" by changing
"deplpyment" to "deployment" so the sentence becomes "Take note of the
deployment ID (DSEQ) generated for use in subsequent steps"; update the single
occurrence in the README content accordingly.
- Line 229: Fix the typo in the README heading: locate the heading string "####
Ping the Deplpyment to Ensure Liveness" and change "Deplpyment" to "Deployment"
so it reads "#### Ping the Deployment to Ensure Liveness".

In `@_run/README.md`:
- Line 73: Fix the grammatical error in the README sentence that currently reads
"PRs with another hosts": update the phrase to correct plural agreement by
replacing "PRs with another hosts" with either "PRs with other hosts" or "PRs
for other hosts" (choose one for consistency with surrounding wording); locate
the sentence text to modify and apply the chosen replacement.
🧹 Nitpick comments (2)
_run/kube/OPERATIONS.md (2)

5-5: Consider hyphenating "two-step process".

The phrase "two step process" should be hyphenated as "two-step process" for correct compound adjective usage.

✏️ Proposed fix
-Updating active Deployments is a two step process. First edit the `deployment.yaml` with whatever changes are desired. Example; update the `image` field.
+Updating active Deployments is a two-step process. First edit the `deployment.yaml` with whatever changes are desired. Example; update the `image` field.

23-25: Add language specifiers to code blocks.

Shell code blocks should include the sh or bash language identifier for proper syntax highlighting.

🎨 Proposed fix

Apply to all shell code blocks:

-```
+```sh
 make bid-close

```diff
-```
+```sh
 make lease-close
</details>


Also applies to: 29-31

</blockquote></details>

</blockquote></details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

Comment on lines +39 to +43
### Tenant closes the group

```sh
make group-pause
```
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Incorrect command for closing a group.

The section "Tenant closes the group" uses make group-pause, which is the same command as "Tenant pauses the group" (lines 33-37). This appears to be a copy-paste error. Based on the naming pattern of other commands (deployment-close, lease-close, bid-close), this should likely be make group-close.

📝 Proposed fix
 ### Tenant closes the group
 
 ```sh
-make group-pause
+make group-close
</details>

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.20.0)</summary>

40-40: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

In @_run/kube/OPERATIONS.md around lines 39 - 43, In the "Tenant closes the
group" section (header "Tenant closes the group") replace the duplicated command
make group-pause with the correct make group-close so the command matches
the naming pattern used for other close operations (e.g., deployment-close,
lease-close, bid-close) and the intended action; update the code block under
that header to contain make group-close.


</details>

<!-- fingerprinting:phantom:triton:puma -->

<!-- This is an auto-generated comment by CodeRabbit -->

#### Create the Deployment

Create a deployment from the `main` account with:
* Take note of the deplpyment ID (DSEQ) generated for use in subsequent steps
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix typo in comment.

"deplpyment" should be "deployment".

✏️ Proposed fix
-* Take note of the deplpyment ID (DSEQ) generated for use in subsequent steps
+* Take note of the deployment ID (DSEQ) generated for use in subsequent steps
📝 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.

Suggested change
* Take note of the deplpyment ID (DSEQ) generated for use in subsequent steps
* Take note of the deployment ID (DSEQ) generated for use in subsequent steps
🧰 Tools
🪛 LanguageTool

[grammar] ~161-~161: Ensure spelling is correct
Context: ...eate the Deployment * Take note of the deplpyment ID (DSEQ) generated for use in subseque...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents
In `@_run/kube/README.md` at line 161, Fix the typo in the README line that reads
"Take note of the deplpyment ID (DSEQ) generated for use in subsequent steps" by
changing "deplpyment" to "deployment" so the sentence becomes "Take note of the
deployment ID (DSEQ) generated for use in subsequent steps"; update the single
occurrence in the README content accordingly.

```

Fetch logs from deployed service (all pods)
#### Ping the Deplpyment to Ensure Liveness
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix typo in heading.

"Deplpyment" should be "Deployment".

✏️ Proposed fix
-#### Ping the Deplpyment to Ensure Liveness
+#### Ping the Deployment to Ensure Liveness
📝 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.

Suggested change
#### Ping the Deplpyment to Ensure Liveness
#### Ping the Deployment to Ensure Liveness
🧰 Tools
🪛 LanguageTool

[grammar] ~229-~229: Ensure spelling is correct
Context: ...rovider-lease-status #### Ping the Deplpyment to Ensure Liveness make provider-...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.20.0)

229-229: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

🤖 Prompt for AI Agents
In `@_run/kube/README.md` at line 229, Fix the typo in the README heading: locate
the heading string "#### Ping the Deplpyment to Ensure Liveness" and change
"Deplpyment" to "Deployment" so it reads "#### Ping the Deployment to Ensure
Liveness".

Run following script to install all system-wide tools. Currently supported host platforms.

* MacOS
* Debian based OS PRs with another hosts are welcome
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix grammatical error.

"PRs with another hosts" should be "PRs with other hosts" or "PRs for other hosts" (plural agreement).

✏️ Proposed fix
-* Debian based OS PRs with another hosts are welcome
+* Debian based OS PRs with other hosts are welcome

Or alternatively:

-* Debian based OS PRs with another hosts are welcome
+* Debian based OS PRs for other hosts are welcome
📝 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.

Suggested change
* Debian based OS PRs with another hosts are welcome
* Debian based OS PRs with other hosts are welcome
🧰 Tools
🪛 LanguageTool

[grammar] ~73-~73: Ensure spelling is correct
Context: ...ms. * MacOS * Debian based OS PRs with another hosts are welcome * Windows is not supp...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents
In `@_run/README.md` at line 73, Fix the grammatical error in the README sentence
that currently reads "PRs with another hosts": update the phrase to correct
plural agreement by replacing "PRs with another hosts" with either "PRs with
other hosts" or "PRs for other hosts" (choose one for consistency with
surrounding wording); locate the sentence text to modify and apply the chosen
replacement.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant