LCORE-1874: Document LLS container startup, teardown, and customization options#1845
Conversation
…on options Documenting all the work being done for [LCORE-1854: Ability to start and teardown LLS from container image](https://redhat.atlassian.net/browse/LCORE-1854) Signed-off-by: Anik Bhattacharjee <anbhatta@redhat.com>
WalkthroughThis PR adds comprehensive documentation for container orchestration in the Lightspeed Core Stack. A new guide explains the ChangesContainer Orchestration Guide
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
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: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/container_orchestration.md (1)
1-740: 🧹 Nitpick | 🔵 Trivial | 💤 Low valueConsider addressing markdown formatting consistency (optional).
The static analysis tool flagged several markdown formatting issues that would improve consistency:
- Blank lines around code blocks (MD031): Many code blocks are missing blank lines before/after
- Language specifiers (MD040): Some code blocks showing example output/errors are missing language hints (could use
textorconsole)- Blank lines around headings (MD022): A few headings in the Advanced Topics section are missing blank lines
These are purely stylistic and don't affect functionality, but addressing them would improve consistency with markdown best practices.
🤖 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 `@docs/container_orchestration.md` around lines 1 - 740, The markdown has styling issues flagged by MD031/MD040/MD022: add blank lines before and after fenced code blocks (e.g., the code blocks in Quick Start, Health Checks and Monitoring, Troubleshooting examples) and ensure blank lines around headings (e.g., the "Advanced Topics" and its subsections) and add language specifiers for fenced code blocks that show output/errors or shell commands (use `bash`, `console`, or `text` as appropriate for blocks like the Quick Start examples, health check outputs, and troubleshooting logs). Locate and update the fenced blocks and headings in the document sections "Quick Start", "Health Checks and Monitoring", "Troubleshooting", and "Advanced Topics" (including "Configuration Enrichment") to insert the missing blank lines and add proper triple-backtick language tags so the markdown linter warnings for MD031, MD040, and MD022 are resolved.
🤖 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 `@docs/container_orchestration.md`:
- Line 371: Replace the unhyphenated compound adjective under the "Start Period"
entry that reads "15 second grace period" with the correctly hyphenated form
"15-second grace period" so the compound adjective is grammatically correct;
locate the "Start Period:" line in docs/container_orchestration.md and update
that phrase.
- Line 129: Update the compound adjective in the documentation: change the
phrase "60 second timeout" to the hyphenated form "60-second timeout" in the
line that reads "Polls container health status (30 attempts × 2 seconds = 60
second timeout)" so the compound adjective correctly modifies "timeout".
---
Outside diff comments:
In `@docs/container_orchestration.md`:
- Around line 1-740: The markdown has styling issues flagged by
MD031/MD040/MD022: add blank lines before and after fenced code blocks (e.g.,
the code blocks in Quick Start, Health Checks and Monitoring, Troubleshooting
examples) and ensure blank lines around headings (e.g., the "Advanced Topics"
and its subsections) and add language specifiers for fenced code blocks that
show output/errors or shell commands (use `bash`, `console`, or `text` as
appropriate for blocks like the Quick Start examples, health check outputs, and
troubleshooting logs). Locate and update the fenced blocks and headings in the
document sections "Quick Start", "Health Checks and Monitoring",
"Troubleshooting", and "Advanced Topics" (including "Configuration Enrichment")
to insert the missing blank lines and add proper triple-backtick language tags
so the markdown linter warnings for MD031, MD040, and MD022 are resolved.
🪄 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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 9781e5a3-5be8-4328-98b8-b90ccf38d7ce
📒 Files selected for processing (3)
README.mddocs/container_orchestration.mddocs/index.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (17)
- GitHub Check: spectral
- GitHub Check: radon
- GitHub Check: check_dependencies
- GitHub Check: build-pr
- GitHub Check: integration_tests (3.12)
- GitHub Check: integration_tests (3.13)
- GitHub Check: Pylinter
- GitHub Check: E2E: server mode / ci / group 3
- GitHub Check: E2E: library mode / ci / group 1
- GitHub Check: E2E: server mode / ci / group 1
- GitHub Check: E2E: server mode / ci / group 2
- GitHub Check: E2E: library mode / ci / group 3
- GitHub Check: E2E: library mode / ci / group 2
- GitHub Check: unit_tests (3.13)
- GitHub Check: unit_tests (3.12)
- GitHub Check: E2E Tests for Lightspeed Evaluation job
- GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2026-05-20T08:09:36.724Z
Learnt from: max-svistunov
Repo: lightspeed-core/lightspeed-stack PR: 1580
File: src/client.py:104-108
Timestamp: 2026-05-20T08:09:36.724Z
Learning: In the lightspeed-stack repo, the synthesized `run.yaml` file handling in `src/client.py` (`_synthesize_library_config`) uses a fixed `/tmp` path intentionally in the PoC (PR `#1580`). The durable production requirements are tracked in spec doc R10 (docs/design/llama-stack-config-merge/llama-stack-config-merge.md): persistent known path overwritten each boot, file mode 0600 set via explicit create flag (not umask), and a `--synthesized-config-output` CLI flag for debugging. The PoC code is scheduled for removal pre-merge; the implementation JIRA "Unified llama_stack.config schema + synthesizer" inherits R10's requirements.
Applied to files:
docs/container_orchestration.md
🪛 LanguageTool
docs/container_orchestration.md
[grammar] ~129-~129: Use a hyphen to join words.
Context: ...lth status (30 attempts × 2 seconds = 60 second timeout) - Shows status on each a...
(QB_NEW_EN_HYPHEN)
[grammar] ~371-~371: Use a hyphen to join words.
Context: ...marking unhealthy - Start Period: 15 second grace period on startup ### LCOR...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.22.1)
docs/container_orchestration.md
[warning] 133-133: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 133-133: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 168-168: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 173-173: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 175-175: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 180-180: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 182-182: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 207-207: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 209-209: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 213-213: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 218-218: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 223-223: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 247-247: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 260-260: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 323-323: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 330-330: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 340-340: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 405-405: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 411-411: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 417-417: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 434-434: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 434-434: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 449-449: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 454-454: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 461-461: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 473-473: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 481-481: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 481-481: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 488-488: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 495-495: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 500-500: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 508-508: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 508-508: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 530-530: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 530-530: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 537-537: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 542-542: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 549-549: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 557-557: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 557-557: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 562-562: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 581-581: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 588-588: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 593-593: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 611-611: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 675-675: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 676-676: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 680-680: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 681-681: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 691-691: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 692-692: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 706-706: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 707-707: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 721-721: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 728-728: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🔇 Additional comments (13)
docs/container_orchestration.md (10)
1-69: LGTM!
78-151: LGTM!
153-186: LGTM!
191-309: LGTM!Also applies to: 311-347
350-370: LGTM!Also applies to: 372-424
427-462: LGTM!Also applies to: 470-615
618-735: LGTM!Also applies to: 739-740
736-738: Verify See Also cross-reference targets exist —docs/okp_guide.md,docs/rag_guide.md,docs/deployment_guide.md, anddocs/getting_started.mdare present, so the See Also links at lines 736-738 point to existing files.
310-310: OKP Guide link is valid
docs/container_orchestration.md’s reference tookp_guide.mdresolves todocs/okp_guide.md, which contains the OKP deployment/setup steps (prerequisites and “Step 1” through “Step 6”).
463-469: Confirm enrichment script CLI flags match the docs
src/llama_stack_configuration.pyexists and itsmain()argparse defines-c/--config,-i/--input, and-o/--output; the documented command-c lightspeed-stack.yaml -i run.yaml -o /tmp/enriched-run.yamlmatches these arguments and passes them intogenerate_configuration(args.input, args.output, ...).README.md (2)
191-191: LGTM!
202-203: LGTM!docs/index.md (1)
29-30: LGTM!
| make wait-for-llama-stack-health | ||
| ``` | ||
|
|
||
| - Polls container health status (30 attempts × 2 seconds = 60 second timeout) |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | ⚡ Quick win
Fix compound adjective hyphenation.
The phrase "60 second timeout" should be hyphenated as "60-second timeout" when used as a compound adjective modifying a noun.
📝 Proposed fix
-- Polls container health status (30 attempts × 2 seconds = 60 second timeout)
+- Polls container health status (30 attempts × 2 seconds = 60-second timeout)📝 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.
| - Polls container health status (30 attempts × 2 seconds = 60 second timeout) | |
| - Polls container health status (30 attempts × 2 seconds = 60-second timeout) |
🧰 Tools
🪛 LanguageTool
[grammar] ~129-~129: Use a hyphen to join words.
Context: ...lth status (30 attempts × 2 seconds = 60 second timeout) - Shows status on each a...
(QB_NEW_EN_HYPHEN)
🤖 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 `@docs/container_orchestration.md` at line 129, Update the compound adjective
in the documentation: change the phrase "60 second timeout" to the hyphenated
form "60-second timeout" in the line that reads "Polls container health status
(30 attempts × 2 seconds = 60 second timeout)" so the compound adjective
correctly modifies "timeout".
| - **Interval:** 10 seconds between checks | ||
| - **Timeout:** 5 seconds per check | ||
| - **Retries:** 3 consecutive failures before marking unhealthy | ||
| - **Start Period:** 15 second grace period on startup |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | ⚡ Quick win
Fix compound adjective hyphenation.
The phrase "15 second grace period" should be hyphenated as "15-second grace period" when used as a compound adjective.
📝 Proposed fix
-- **Start Period:** 15 second grace period on startup
+- **Start Period:** 15-second grace period on startup📝 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.
| - **Start Period:** 15 second grace period on startup | |
| - **Start Period:** 15-second grace period on startup |
🧰 Tools
🪛 LanguageTool
[grammar] ~371-~371: Use a hyphen to join words.
Context: ...marking unhealthy - Start Period: 15 second grace period on startup ### LCOR...
(QB_NEW_EN_HYPHEN)
🤖 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 `@docs/container_orchestration.md` at line 371, Replace the unhyphenated
compound adjective under the "Start Period" entry that reads "15 second grace
period" with the correctly hyphenated form "15-second grace period" so the
compound adjective is grammatically correct; locate the "Start Period:" line in
docs/container_orchestration.md and update that phrase.
tisnik
changed the title
2 participants
Description
Documenting all the work being done for
LCORE-1854: Ability to start and teardown LLS from container image
Type of change
Tools used to create PR
Identify any AI code assistants used in this PR (for transparency and review context)
Related Tickets & Documents
Checklist before requesting a review
Testing
Summary by CodeRabbit
make runand reference links to detailed guides.