feat(features): Add Memory Vertical Scaling feature#165
Open
victorduta wants to merge 2 commits into
Open
Conversation
Signed-off-by: Victor Duta <victor@unikraft.io>
| ::: | ||
|
|
||
| Unikraft Cloud supports the ability to create instances that automatically scale their memory based on the current guest memory utilisation. | ||
| Without the feature, all memory alloted to the machine is boot memory and when the guest utilises memory pages at least once they remain |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Microsoft.SentenceLength] Try to keep sentences short (< 30 words).
|
|
||
| Unikraft Cloud supports the ability to create instances that automatically scale their memory based on the current guest memory utilisation. | ||
| Without the feature, all memory alloted to the machine is boot memory and when the guest utilises memory pages at least once they remain | ||
| resident even after the guest stops utilising them (i.e., even free guest memory will consume host system RAM). |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Foreign] Use 'that is' instead of 'i.e.,'.
| Without the feature, all memory alloted to the machine is boot memory and when the guest utilises memory pages at least once they remain | ||
| resident even after the guest stops utilising them (i.e., even free guest memory will consume host system RAM). | ||
| With vertical scaling, once the in-guest memory utilisation drops bellow some watermark the host will **reclaim** this | ||
| memory and potentially allocate it to other instances. |
Contributor
There was a problem hiding this comment.
[Microsoft.Adverbs] Remove 'potentially' if it's not important to the meaning of the statement.
| Without the feature, all memory alloted to the machine is boot memory and when the guest utilises memory pages at least once they remain | ||
| resident even after the guest stops utilising them (i.e., even free guest memory will consume host system RAM). | ||
| With vertical scaling, once the in-guest memory utilisation drops bellow some watermark the host will **reclaim** this | ||
| memory and potentially allocate it to other instances. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[write-good.TooWordy] 'allocate' is too wordy.
|
|
||
| With **Memory Vertical Scaling** the user can specify a min memory and max memory field during instance creation. | ||
| As a result the new instance's memory will automatically scale between min and max based on its current memory utilisation. | ||
| The feature requires building your application against the latest TinyX kernel since the core of the feature is an in-guest kernel thread that handles memory accounting and notifying the platform to scale up/down its memory. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Microsoft.SentenceLength] Try to keep sentences short (< 30 words).
|
|
||
| This will create an image with an 8GB volume mounted at /mnt/postgres where we add the **data** and **wal** files. | ||
| The instance will start with 756MB memory but depending on the memory utilisation of the system it will scale its memory between 512MB and 32GB. | ||
| The information is specified by the **memory_mb** (default memory), **min_memory_mb** (min memory) and **max_memory_mb** (max memory) parameters. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[write-good.Passive] 'is specified' may be passive voice. Use active voice if you can.
| ``` | ||
| This will actively pull memory information from the instance using postgres. | ||
|
|
||
| Now run a script using (e.g., pg_bench) to stress test the instance. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Foreign] Use 'for example' instead of 'e.g.,'.
| This will actively pull memory information from the instance using postgres. | ||
|
|
||
| Now run a script using (e.g., pg_bench) to stress test the instance. | ||
| The script bellow for example runs a couple of tests (database creation, select workload, etc.) with the instance we just created. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'we'.
| This will actively pull memory information from the instance using postgres. | ||
|
|
||
| Now run a script using (e.g., pg_bench) to stress test the instance. | ||
| The script bellow for example runs a couple of tests (database creation, select workload, etc.) with the instance we just created. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Unikraft.NeutralTone] Use a neutral tone; avoid 'just'. Prefer precise, factual wording.
|
|
||
| Now run a script using (e.g., pg_bench) to stress test the instance. | ||
| The script bellow for example runs a couple of tests (database creation, select workload, etc.) with the instance we just created. | ||
| One should see the instance actively adding memory once utilisation grows above some configurable utilisation percentage (80% by |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Microsoft.SentenceLength] Try to keep sentences short (< 30 words).
Signed-off-by: Victor Duta <victor@unikraft.io>
| Unikraft Cloud supports the ability to create instances that automatically scale their memory based on the current guest memory utilisation. | ||
| Without the feature, all memory alloted to the machine is boot memory and when the guest utilises memory pages at least once they remain | ||
| resident even after the guest stops utilising them. | ||
| In other words, even free guest memory will consume host system RAM, after it is used once. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'it's' instead of 'it is'.
| Unikraft Cloud supports the ability to create instances that automatically scale their memory based on the current guest memory utilisation. | ||
| Without the feature, all memory alloted to the machine is boot memory and when the guest utilises memory pages at least once they remain | ||
| resident even after the guest stops utilising them. | ||
| In other words, even free guest memory will consume host system RAM, after it is used once. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[write-good.TooWordy] 'it is' is too wordy.
| Unikraft Cloud supports the ability to create instances that automatically scale their memory based on the current guest memory utilisation. | ||
| Without the feature, all memory alloted to the machine is boot memory and when the guest utilises memory pages at least once they remain | ||
| resident even after the guest stops utilising them. | ||
| In other words, even free guest memory will consume host system RAM, after it is used once. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[write-good.Passive] 'is used' may be passive voice. Use active voice if you can.
|
|
||
| With **Memory Vertical Scaling** the user can specify a min memory and max memory field during instance creation. | ||
| As a result the new instance's memory will automatically scale between min and max based on its current memory utilisation. | ||
| The feature requires building your app against the latest TinyX kernel since the core component is an in-guest kernel thread that handles memory accounting and notifying the platform to scale up/down its memory. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Microsoft.SentenceLength] Try to keep sentences short (< 30 words).
There was a problem hiding this comment.
Pull request overview
Adds documentation for a new “Memory Vertical Scaling” feature tutorial and exposes it in the docs navigation, focused on deploying PostgreSQL with memory vertical scaling enabled.
Changes:
- Added a new docs page: Memory Vertical Scaling tutorial (PostgreSQL example + stress-testing scripts).
- Linked the new page into the Features section of the site navigation.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 11 comments.
| File | Description |
|---|---|
zudoku.config.tsx |
Adds /features/mem-vscaling to the Features navigation list. |
pages/features/mem-vscaling.mdx |
New documentation page describing memory vertical scaling and a PostgreSQL walkthrough. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+13
to
+17
| Without the feature, all memory alloted to the machine is boot memory and when the guest utilises memory pages at least once they remain | ||
| resident even after the guest stops utilising them. | ||
| In other words, even free guest memory will consume host system RAM, after it is used once. | ||
| With vertical scaling, once the in-guest memory utilisation drops bellow some watermark the host will **reclaim** this | ||
| memory and use it for other instances. |
| export UKC_METRO="fra" # or your preferred metro | ||
| ``` | ||
|
|
||
| ### Creating and running postgress image. |
Comment on lines
+88
to
+92
| -H "Authorization: Bearer $UKC_TOKEN" \ | ||
| -H "Content-Type: application/json" \ | ||
| "$UKC_METRO/instances" \ | ||
| -d "{ | ||
| 'name' : 'test-postgres-vertical', |
Comment on lines
+93
to
+96
| 'image': '${UKC_USER}/postgres-vertical:latest', | ||
| 'args': [ | ||
| '/usr/local/bin/wrapper.sh', 'postgres', '-c', 'shared_preload_libraries="pg_ukc_scaletozero"' | ||
| ], |
Comment on lines
+97
to
+104
| 'autostart': true, | ||
| 'memory_mb': 756, | ||
| 'vscaling' : {'min_memory_mb' : 512, 'max_memory_mb' : 32000}, | ||
| 'env': {'POSTGRES_PASSWORD' : 'unikraft', 'POSTGRES_INITDB_WALDIR' : '/mnt/postgres/wal', 'PGDATA' : '/mnt/postgres/data', 'POSTGRES_DB' : 'stress_db'}, | ||
| 'scale_to_zero': { | ||
| 'policy': 'off' | ||
| }, | ||
| 'volumes' : [{'at': '/mnt/postgres', 'size_mb': 8096}], |
Comment on lines
+149
to
+154
| Now run a script using (for example, pg_bench) to stress test the instance. | ||
| The script bellow for example runs a couple of tests (database creation, select workload, etc.) with the created instance. | ||
| One should see the instance actively adding memory once utilisation grows above some configurable utilisation percentage (80% by | ||
| default). | ||
| Conversely once utilisation drops bellow some configurable percentage (30% by default), the total memory of the instance will go | ||
| down. |
Comment on lines
+486
to
+487
| : << 'COMMENT' | ||
| COMMENT |
Comment on lines
+606
to
+615
| log "Removing old WAL files via pg_archivecleanup (keeping only current)..." | ||
| psql_sys -tAc "SELECT pg_walfile_name(pg_current_wal_lsn());" 2>/dev/null | while read -r current_wal; do | ||
| if [[ -n "${current_wal:-}" ]]; then | ||
| log "Current WAL file: ${current_wal}" | ||
| psql_sys -c " | ||
| COPY (SELECT 1) TO PROGRAM | ||
| 'find \$(dirname \$(readlink -f \$(pg_ctl -D \$PGDATA status 2>/dev/null | grep -o \"PID: [0-9]*\" | awk \"{print \$2}\" | xargs -I{} ls -la /proc/{}/fd 2>/dev/null | grep pg_wal | head -1 | awk \"{print \$NF}\"))) -name \"*.wal\" -o -name \"[0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F]\" | sort | head -n -1 | xargs rm -f'; | ||
| " 2>/dev/null || true | ||
| fi | ||
| done |
Comment on lines
+617
to
+629
| log "Cleaning WAL via pg_ls_waldir (removing all but current segment)..." | ||
| psql_sys -c " | ||
| COPY (SELECT 1) TO PROGRAM \$cmd\$ | ||
| sh -c ' | ||
| PGDATA=\$(psql -tAc \"SHOW data_directory\" 2>/dev/null || echo \"\") | ||
| if [ -n \"\${PGDATA}\" ]; then | ||
| WALDIR=\${PGDATA}/pg_wal | ||
| CURRENT=\$(psql -tAc \"SELECT pg_walfile_name(pg_current_wal_lsn())\" 2>/dev/null) | ||
| find \${WALDIR} -maxdepth 1 -type f ! -name \"\${CURRENT}\" ! -name \"*.history\" -delete | ||
| echo \"WAL files cleaned, kept: \${CURRENT}\" | ||
| fi | ||
| ' | ||
| \$cmd\$;" 2>/dev/null && ok "WAL files cleaned" || warn "Could not clean WAL files directly — checkpoint was sufficient" |
| echo " < 95% → memory too small for load ❌" | ||
| echo "" | ||
| echo "Re-run with different scale or load:" | ||
| echo " DB_SCALE=64 CLIENTS=128 DURATION=300 ./pg_memory_stress.sh" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A short tutorial on how to run postgres with memory vertical scaling.