Improve GraalVM and scalability guides

[Dilhasha]

$subject

Summary by CodeRabbit

• Documentation
  • Revised GraalVM native images guide: added a JVM vs Native Image comparison, updated prerequisites for GraalVM/JDK 21, added SDKMAN installation and GRAALVM_HOME guidance, and introduced native compatibility testing with bal test --graalvm. Removed detailed native deployment examples.
  • Reworked scaling & high availability guidance to favor Cloud.toml-driven autoscaling and high-level orchestration best practices over low-level Kubernetes YAML examples.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3530d234-e571-41bc-bcb0-0e207db7dded

📥 Commits

Reviewing files that changed from the base of the PR and between 1b0894a and c2833e7.

📒 Files selected for processing (1)

• en/docs/deploy-operate/deploy/graalvm-native-images.md

✅ Files skipped from review due to trivial changes (1)

• en/docs/deploy-operate/deploy/graalvm-native-images.md

---

📝 Walkthrough

Walkthrough

This PR updates two deployment docs: the GraalVM native-image guide now targets GraalVM for JDK 21, expands SDKMAN and GRAALVM_HOME install instructions, adds bal test --graalvm testing notes, and removes the deployment section; the scaling/HA guide shifts from Kubernetes YAML examples to Cloud.toml-driven auto-scaling and prose-based HA guidance.

Changes

GraalVM Native Images Documentation Overhaul

Layer / File(s)	Summary
JVM vs Native Image introduction and prerequisites en/docs/deploy-operate/deploy/graalvm-native-images.md	Section header changed from "Benefits" to "JVM vs Native Image"; prerequisites table updated to target GraalVM for JDK 21 with revised memory and Docker guidance.
GraalVM installation and platform-specific setup en/docs/deploy-operate/deploy/graalvm-native-images.md	Installation instructions expanded with SDKMAN-based commands and explicit GRAALVM_HOME setup (Linux/macOS and Windows examples); platform-specific notes for Windows, macOS (Apple Silicon), and Linux added.
Native compatibility testing en/docs/deploy-operate/deploy/graalvm-native-images.md	New "Test native compatibility" section documents bal test --graalvm usage and notes that code coverage and runtime debugging are not supported.
Removal of deprecated deployment section en/docs/deploy-operate/deploy/graalvm-native-images.md	Entire "Deploying native images" section removed; document now transitions directly from build options to troubleshooting.

Scaling and High Availability Documentation Transition

Layer / File(s)	Summary
Cloud.toml-driven auto-scaling and load balancing en/docs/deploy-operate/deploy/scaling-high-availability.md	Replaces "Kubernetes replica scaling" with "Cloud.toml auto-scaling"; notes that bal build --cloud=k8s generates HorizontalPodAutoscaler resources and replaces concrete Service/Ingress/session affinity YAML with higher-level load-balancing and health-endpoint guidance.
High availability strategies and graceful shutdown en/docs/deploy-operate/deploy/scaling-high-availability.md	Removes Kubernetes probe/topology/PDB YAML examples and adds prose-based guidance for orchestrator probe configuration, multi-zone deployment, minimum instance counts, PodDisruptionBudget reference, and a condensed graceful shutdown sequence (terminationGracePeriodSeconds/preStop).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• wso2/docs-integrator#520: Also touches the GraalVM native images documentation and related deployment guidance.

Suggested reviewers

• rosensilva
• NipunaRanasinghe
• KavinduZoysa
• anupama-pathirage
• anuruddhal

Poem

🐰 A rabbit reads the docs at night,
Balances GraalVM with gentle light,
SDKMAN whispers paths to HOME,
Cloud.toml helps the autoscale roam,
Docs trimmed clean — the garden's bright!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description is blank (only '$subject' placeholder), completely missing all required template sections including Purpose, Goals, Approach, User stories, Release notes, and Documentation details.	Fill in all required sections from the description template, particularly Purpose (with issue links), Goals, Approach, Release notes, and Documentation links to explain the improvements made.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Improve GraalVM and scalability guides' directly reflects the two main documentation updates—GraalVM native images and scaling/high-availability guides—making it clear, specific, and aligned with the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

en/docs/deploy-operate/deploy/scaling-high-availability.md (1)

48-49: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use valid Cloud.toml autoscaling keys (cpu, memory)

The example currently uses cpu_threshold/memory_threshold, which does not match the documented [cloud.deployment.autoscaling] schema and can cause users to copy invalid config.

Suggested fix

 [cloud.deployment.autoscaling]
 min_replicas = 2
 max_replicas = 10
-cpu_threshold = 70
-memory_threshold = 80
+cpu = 70
+memory = 80

🤖 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 `@en/docs/deploy-operate/deploy/scaling-high-availability.md` around lines 48 -
49, Replace the invalid autoscaling keys cpu_threshold and memory_threshold with
the schema-accurate keys cpu and memory under the [cloud.deployment.autoscaling]
section; update any example lines that currently show "cpu_threshold = 70" and
"memory_threshold = 80" to use "cpu = 70" and "memory = 80" so the example
matches the documented Cloud.toml schema.

🤖 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 `@en/docs/deploy-operate/deploy/graalvm-native-images.md`:
- Line 11: The H2 header text "## JVM vs Native Image" uses title case; change
it to sentence case by updating the header string (the header line containing
"JVM vs Native Image") to "## JVM vs native image" so it follows sentence-case
style for non-H1 headings in the document.

---

Outside diff comments:
In `@en/docs/deploy-operate/deploy/scaling-high-availability.md`:
- Around line 48-49: Replace the invalid autoscaling keys cpu_threshold and
memory_threshold with the schema-accurate keys cpu and memory under the
[cloud.deployment.autoscaling] section; update any example lines that currently
show "cpu_threshold = 70" and "memory_threshold = 80" to use "cpu = 70" and
"memory = 80" so the example matches the documented Cloud.toml schema.

🪄 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: CHILL

Plan: Pro

Run ID: 48eb3c50-6159-46e4-ad86-5715d05b6b0a

📥 Commits

Reviewing files that changed from the base of the PR and between 50f5c02 and 1b0894a.

📒 Files selected for processing (2)

• en/docs/deploy-operate/deploy/graalvm-native-images.md
• en/docs/deploy-operate/deploy/scaling-high-availability.md

[Dilhasha]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.