From dfc525838a7e58949e21269f9d503ec3649bb6f7 Mon Sep 17 00:00:00 2001 From: Tianyu Zhou Date: Sat, 19 Sep 2026 10:30:37 +0800 Subject: [PATCH 1/2] feat: expose shared ChunkDB capacity in node deployments Add optional capacity settings for standalone, Helm, and both cloud Terraform modules, including guided profile generation. Preserve the existing distill-fs default when no override is supplied and validate input syntax before rendering the node configuration. Document consistent node-wide configuration, supported size units, and the cache replacement required when changing capacity. Custom templates retain a marker so overrides cannot silently miss the image configuration. Signed-off-by: Tianyu Zhou --- AGENTS.md | 9 +++++++++ Makefile | 2 ++ deploy/README.md | 8 ++++++++ .../charts/core/templates/node/configmap.yaml | 11 +++++++++++ deploy/akernel/charts/core/values.yaml | 3 +++ deploy/scripts/configure.sh | 12 ++++++++++++ deploy/standalone/config/sandboxd_config.toml | 1 + deploy/standalone/start.sh | 15 +++++++++++++++ deploy/terraform/aliyun/main.tf | 1 + deploy/terraform/aliyun/values-akernel.yaml.tmpl | 2 ++ deploy/terraform/aliyun/variables.tf | 10 ++++++++++ deploy/terraform/huaweicloud/main.tf | 1 + .../huaweicloud/values-akernel.yaml.tmpl | 2 ++ deploy/terraform/huaweicloud/variables.tf | 10 ++++++++++ 14 files changed, 87 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 351542a9..bdb4fee7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -172,6 +172,15 @@ Never use a guessed checksum or silently fall back to a source build. Missing or invalid release pins prevent builds. `make versions` reports the release tag and archive digest without requiring the distill-fs submodule. +The optional node-wide ChunkDB capacity is configured with standalone +`AKERNEL_CHUNK_DB_SIZE`, Helm `node.config.sandboxd.chunkDbSize` (under +`core` in the umbrella chart), or Terraform `chunk_db_size`. Guided profiles +accept `make config CHUNK_DB_SIZE=64GiB`. Empty values preserve the Linux +100 GiB default. Sandboxd passes the same capacity to every distill-fs user; +existing-cache resizing is unsupported. Preserve the +`# AKERNEL_CHUNK_DB_SIZE` marker in custom deployment templates. See +`deploy/README.md#shared-chunkdb-capacity` for cache replacement semantics. + Each component embeds its own semantic version: sandboxd uses `version/VERSION`, while distill-fs uses its release package version in `Cargo.toml`. AKernel does not inject parent-repository version metadata into diff --git a/Makefile b/Makefile index 918b9284..64edf86f 100644 --- a/Makefile +++ b/Makefile @@ -31,6 +31,7 @@ ACR_NAMESPACE ?= MONITOR_STORAGE_CLASS ?= INSTALL_MONITOR ?= INSTALL_DRAGONFLY ?= +CHUNK_DB_SIZE ?= ENABLE_RUNC ?= SCHEDULE_PLACEMENT_POLICY ?= GRAFANA_PUBLIC_ACCESS ?= @@ -93,6 +94,7 @@ config: if [[ -n "$(IMAGE_TAG)" ]]; then args+=(--image-tag "$(IMAGE_TAG)"); fi; \ if [[ -n "$(INSTALL_MONITOR)" ]]; then args+=(--install-monitor "$(INSTALL_MONITOR)"); fi; \ if [[ -n "$(INSTALL_DRAGONFLY)" ]]; then args+=(--install-dragonfly "$(INSTALL_DRAGONFLY)"); fi; \ + if [[ -n "$(CHUNK_DB_SIZE)" ]]; then args+=(--chunk-db-size "$(CHUNK_DB_SIZE)"); fi; \ if [[ -n "$(ENABLE_RUNC)" ]]; then args+=(--enable-runc "$(ENABLE_RUNC)"); fi; \ if [[ -n "$(SCHEDULE_PLACEMENT_POLICY)" ]]; then args+=(--schedule-placement-policy "$(SCHEDULE_PLACEMENT_POLICY)"); fi; \ if [[ -n "$(GRAFANA_PUBLIC_ACCESS)" ]]; then args+=(--grafana-public-access "$(GRAFANA_PUBLIC_ACCESS)"); fi; \ diff --git a/deploy/README.md b/deploy/README.md index 03778c05..79663985 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -404,3 +404,11 @@ The all-in-one image downloads the static Linux/amd64 distill-fs release pinned Publish and verify the distill-fs release before updating the AKernel version, URL, and checksum pin together. Missing or invalid pins stop `make build` before either image is built. There is no source-build fallback. Validate installation against a downloaded candidate or release with `python3 builder/scripts/test-install-distill-fs.py /path/to/distill-fs-vX.Y.Z-linux-amd64.tar.gz` on Linux/amd64 with curl, jq, and binutils. This checks normal installation and rejects missing/invalid pins, corrupted archives, version/architecture mismatch, binary hash mismatch, and dynamically linked executables. The sandboxd pipeline and gitlink are independent of this dependency. + +## Shared ChunkDB capacity + +The node image's distill-fs v0.1.2 supports a configurable shared image-cache database capacity. The Linux default remains 100 GiB when omitted. Set `AKERNEL_CHUNK_DB_SIZE=64GiB` for standalone, `core.node.config.sandboxd.chunkDbSize=64GiB` in the umbrella Helm chart (`node.config.sandboxd.chunkDbSize` in the core chart), or `chunk_db_size = "64GiB"` in either cloud Terraform module. Guided profiles accept `make config CHUNK_DB_SIZE=64GiB`; this records the value in the generated Terraform configuration. Use a node image built with the matching sandboxd and distill-fs pins before enabling this option. + +Whole bytes and integer `B`, `KiB`, `MiB`, `GiB`, or `TiB` values are supported. Sandboxd validates the minimum of 1 MiB, addressability, and host page alignment and supplies the same capacity to mounts, stats, GC, and recovered daemons. This is the LMDB map limit, not a memory reservation, a whole-cache disk quota, or a sandbox `storage_mb` limit. + +Resizing an existing cache is unsupported. Same-Pod service restarts retain it; a replacement Pod with a changed hostname clears the image-manager root and creates a new cache with the configured capacity. Drain workloads before replacement. Standalone deployments must stop all users and select a fresh image-manager cache directory when changing capacity. Custom sandboxd configuration templates must retain the `# AKERNEL_CHUNK_DB_SIZE` marker when using the standalone or Helm override. diff --git a/deploy/akernel/charts/core/templates/node/configmap.yaml b/deploy/akernel/charts/core/templates/node/configmap.yaml index bfc89890..bb559c8d 100644 --- a/deploy/akernel/charts/core/templates/node/configmap.yaml +++ b/deploy/akernel/charts/core/templates/node/configmap.yaml @@ -21,6 +21,17 @@ data: {{- end }} {{- $sandboxdConfig = replace $runcMarker "runc=\"/usr/local/bin/runc\"" $sandboxdConfig }} {{- end }} +{{- $chunkDbSize := .Values.node.config.sandboxd.chunkDbSize | default "" }} +{{- if $chunkDbSize }} +{{- if not (regexMatch "^[0-9]+(B|KiB|MiB|GiB|TiB)?$" $chunkDbSize) }} +{{- fail "node.config.sandboxd.chunkDbSize must be whole bytes or an integer with B/KiB/MiB/GiB/TiB" }} +{{- end }} +{{- $chunkDbMarker := "# AKERNEL_CHUNK_DB_SIZE" }} +{{- if not (contains $chunkDbMarker $sandboxdConfig) }} +{{- fail "node.config.sandboxd.chunkDbSize requires the # AKERNEL_CHUNK_DB_SIZE marker in node.config.sandboxd.config" }} +{{- end }} +{{- $sandboxdConfig = replace $chunkDbMarker (printf "chunk_db_size=%s" ($chunkDbSize | quote)) $sandboxdConfig }} +{{- end }} {{ $sandboxdConfig | indent 4 }} registry.json: | diff --git a/deploy/akernel/charts/core/values.yaml b/deploy/akernel/charts/core/values.yaml index fa68ee90..afead83a 100644 --- a/deploy/akernel/charts/core/values.yaml +++ b/deploy/akernel/charts/core/values.yaml @@ -451,6 +451,8 @@ node: # The node image must also be built with AKERNEL_ENABLE_RUNC=true. # Sandboxd probes runc and runc-shim before advertising the runtime. enableRunc: false + # Empty uses the distill-fs default (100 GiB on Linux). + chunkDbSize: "" config: |- rootDir="/home/akernel/sandboxd/root" storeDir="/home/akernel/sandboxd/store" @@ -519,6 +521,7 @@ node: # configs live under /home/akernel/sandboxd/config/ so the wipe never # hits the read-only bind-mounted config files. [plugin.image] + # AKERNEL_CHUNK_DB_SIZE root="/home/akernel/sandboxd/image_manager" distill_fs_bin="/usr/local/bin/distill_fs" oss_template="/home/akernel/sandboxd/config/oss.json" diff --git a/deploy/scripts/configure.sh b/deploy/scripts/configure.sh index ceec4db5..0a834c27 100755 --- a/deploy/scripts/configure.sh +++ b/deploy/scripts/configure.sh @@ -30,6 +30,7 @@ image_repository_override="" image_tag_override="" install_monitor_override="" install_dragonfly_override="" +chunk_db_size_override="" enable_runc_override="" schedule_placement_policy_override="" grafana_public_access_override="" @@ -118,6 +119,10 @@ while [[ $# -gt 0 ]]; do install_dragonfly_override="$2" shift 2 ;; + --chunk-db-size) + chunk_db_size_override="$2" + shift 2 + ;; --enable-runc) enable_runc_override="$2" shift 2 @@ -238,6 +243,10 @@ esac set_or_prompt image_tag "All-in-one image tag" "${default_tag}" "${image_tag_override}" set_or_prompt install_monitor "Install monitor chart (true/false)" "true" "${install_monitor_override}" set_or_prompt install_dragonfly "Install Dragonfly and dedicated node pools (true/false)" "false" "${install_dragonfly_override}" +set_or_prompt chunk_db_size "Shared ChunkDB capacity (empty uses distill-fs default)" "" "${chunk_db_size_override}" +if [[ -n "${chunk_db_size}" && ! "${chunk_db_size}" =~ ^[0-9]+(B|KiB|MiB|GiB|TiB)?$ ]]; then + die "CHUNK_DB_SIZE must be whole bytes or an integer with B/KiB/MiB/GiB/TiB" +fi set_or_prompt enable_runc "Enable the optional runc runtime (true/false)" "false" "${enable_runc_override}" set_or_prompt schedule_placement_policy \ "YuanRong schedule placement policy (binpack/spread)" "spread" \ @@ -373,6 +382,7 @@ grafana_public_access = ${grafana_public_access} grafana_admin_password = "${grafana_admin_password}" install_dragonfly = ${install_dragonfly} +chunk_db_size = "${chunk_db_size}" enable_runc = ${enable_runc} schedule_placement_policy = "${schedule_placement_policy}" EOF @@ -428,6 +438,7 @@ grafana_public_access = ${grafana_public_access} grafana_admin_password = "${grafana_admin_password}" install_dragonfly = ${install_dragonfly} +chunk_db_size = "${chunk_db_size}" enable_runc = ${enable_runc} schedule_placement_policy = "${schedule_placement_policy}" EOF @@ -450,6 +461,7 @@ IMAGE_TAG=${image_tag} CORE_NAMESPACE=akernel MONITOR_NAMESPACE=akernel-monitor INSTALL_DRAGONFLY=${install_dragonfly} +CHUNK_DB_SIZE=${chunk_db_size} AKERNEL_ENABLE_RUNC=${enable_runc} SCHEDULE_PLACEMENT_POLICY=${schedule_placement_policy} EOF diff --git a/deploy/standalone/config/sandboxd_config.toml b/deploy/standalone/config/sandboxd_config.toml index d0bf1386..50ea4d94 100644 --- a/deploy/standalone/config/sandboxd_config.toml +++ b/deploy/standalone/config/sandboxd_config.toml @@ -71,6 +71,7 @@ kvm_device="/dev/kvm" # on pod change; input configs live under /home/akernel/sandboxd/config/ so the # wipe never hits them. [plugin.image] +# AKERNEL_CHUNK_DB_SIZE root="/home/akernel/sandboxd/image_manager" distill_fs_bin="/usr/local/bin/distill_fs" oss_template="/home/akernel/sandboxd/config/oss.json" diff --git a/deploy/standalone/start.sh b/deploy/standalone/start.sh index 9d1a20a3..718607c0 100755 --- a/deploy/standalone/start.sh +++ b/deploy/standalone/start.sh @@ -23,6 +23,7 @@ TOKEN_FILE="${DATA_DIR}/token" SANDBOXD_CONFIG_FILE="${DATA_DIR}/sandboxd/config.toml" AKERNEL_NAT_BACKEND="${AKERNEL_NAT_BACKEND:-iptables}" AKERNEL_ENABLE_RUNC="${AKERNEL_ENABLE_RUNC:-false}" +AKERNEL_CHUNK_DB_SIZE="${AKERNEL_CHUNK_DB_SIZE:-}" YR_IMAGE_PROCESS_CONFIG="${YR_IMAGE_PROCESS_CONFIG:-/run/akernel/yr-image-process.json}" LITEBUS_DATA_KEY="" @@ -268,6 +269,20 @@ configure_network() { -e 's|^[[:space:]]*# AKERNEL_RUNTIME_RUNC[[:space:]]*$|runc="/usr/local/bin/runc"|' ) fi + if [[ -n "${AKERNEL_CHUNK_DB_SIZE}" ]]; then + if [[ ! "${AKERNEL_CHUNK_DB_SIZE}" =~ ^[0-9]+(B|KiB|MiB|GiB|TiB)?$ ]]; then + log_error "AKERNEL_CHUNK_DB_SIZE must be whole bytes or an integer with B/KiB/MiB/GiB/TiB" + exit 1 + fi + if ! grep -q '^[[:space:]]*# AKERNEL_CHUNK_DB_SIZE[[:space:]]*$' \ + "${CONFIG_DIR}/sandboxd_config.toml"; then + log_error "AKERNEL_CHUNK_DB_SIZE requires the # AKERNEL_CHUNK_DB_SIZE marker in sandboxd_config.toml" + exit 1 + fi + sed_args+=( + -e "s|^[[:space:]]*# AKERNEL_CHUNK_DB_SIZE[[:space:]]*$|chunk_db_size=\"${AKERNEL_CHUNK_DB_SIZE}\"|" + ) + fi sed "${sed_args[@]}" "${CONFIG_DIR}/sandboxd_config.toml" > "${config_tmp}" mv "${config_tmp}" "${SANDBOXD_CONFIG_FILE}" diff --git a/deploy/terraform/aliyun/main.tf b/deploy/terraform/aliyun/main.tf index 08e5a024..c256d4ca 100644 --- a/deploy/terraform/aliyun/main.tf +++ b/deploy/terraform/aliyun/main.tf @@ -157,6 +157,7 @@ locals { master_service_type = (var.master_public_access_8888 && !var.traefik_enabled) ? var.master_service_type : "ClusterIP" traefik_enabled = var.traefik_enabled sandboxd_nat_backend = var.sandboxd_nat_backend + chunk_db_size = var.chunk_db_size enable_runc = var.enable_runc node_secret_create = var.node_secret_create node_home_use_csi_ephemeral = var.node_home_use_csi_ephemeral diff --git a/deploy/terraform/aliyun/values-akernel.yaml.tmpl b/deploy/terraform/aliyun/values-akernel.yaml.tmpl index 4b8087f4..d0d477d0 100644 --- a/deploy/terraform/aliyun/values-akernel.yaml.tmpl +++ b/deploy/terraform/aliyun/values-akernel.yaml.tmpl @@ -146,6 +146,7 @@ node: cpuQuota: "100%" sandboxd: enableRunc: ${enable_runc} + chunkDbSize: ${jsonencode(chunk_db_size)} config: |- rootDir="/home/akernel/sandboxd/root" storeDir="/home/akernel/sandboxd/store" @@ -213,6 +214,7 @@ node: # configs live under /home/akernel/sandboxd/config/ so the wipe never # hits the read-only bind-mounted config files. [plugin.image] + # AKERNEL_CHUNK_DB_SIZE root="/home/akernel/sandboxd/image_manager" distill_fs_bin="/usr/local/bin/distill_fs" oss_template="/home/akernel/sandboxd/config/oss.json" diff --git a/deploy/terraform/aliyun/variables.tf b/deploy/terraform/aliyun/variables.tf index c0c70ddf..ee042320 100644 --- a/deploy/terraform/aliyun/variables.tf +++ b/deploy/terraform/aliyun/variables.tf @@ -966,3 +966,13 @@ variable "tempo_resources" { }) default = {} } + +variable "chunk_db_size" { + type = string + description = "Shared distill-fs ChunkDB map capacity, e.g. 64GiB; empty uses the Linux default of 100 GiB. Existing caches must not be resized." + default = "" + validation { + condition = var.chunk_db_size == "" || can(regex("^[0-9]+(B|KiB|MiB|GiB|TiB)?$", var.chunk_db_size)) + error_message = "chunk_db_size must be empty, whole bytes, or an integer with B/KiB/MiB/GiB/TiB." + } +} diff --git a/deploy/terraform/huaweicloud/main.tf b/deploy/terraform/huaweicloud/main.tf index 984674b5..48880ee1 100644 --- a/deploy/terraform/huaweicloud/main.tf +++ b/deploy/terraform/huaweicloud/main.tf @@ -113,6 +113,7 @@ locals { master_service_annotations = merge(local.huaweicloud_master_elb_annotations, var.master_service_annotations) master_service_loadbalancer_ip = var.master_public_access_8888 ? var.master_service_loadbalancer_ip : "" sandboxd_nat_backend = var.sandboxd_nat_backend + chunk_db_size = var.chunk_db_size enable_runc = var.enable_runc node_secret_create = var.node_secret_create node_home_use_csi_ephemeral = var.node_home_use_csi_ephemeral diff --git a/deploy/terraform/huaweicloud/values-akernel.yaml.tmpl b/deploy/terraform/huaweicloud/values-akernel.yaml.tmpl index 5f2207bc..624c163d 100644 --- a/deploy/terraform/huaweicloud/values-akernel.yaml.tmpl +++ b/deploy/terraform/huaweicloud/values-akernel.yaml.tmpl @@ -126,6 +126,7 @@ node: cpuQuota: "100%" sandboxd: enableRunc: ${enable_runc} + chunkDbSize: ${jsonencode(chunk_db_size)} config: |- rootDir="/home/akernel/sandboxd/root" storeDir="/home/akernel/sandboxd/store" @@ -191,6 +192,7 @@ node: # configs live under /home/akernel/sandboxd/config/ so the wipe never # hits the read-only bind-mounted config files. [plugin.image] + # AKERNEL_CHUNK_DB_SIZE root="/home/akernel/sandboxd/image_manager" distill_fs_bin="/usr/local/bin/distill_fs" oss_template="/home/akernel/sandboxd/config/oss.json" diff --git a/deploy/terraform/huaweicloud/variables.tf b/deploy/terraform/huaweicloud/variables.tf index 54152f47..e0feed65 100644 --- a/deploy/terraform/huaweicloud/variables.tf +++ b/deploy/terraform/huaweicloud/variables.tf @@ -1000,3 +1000,13 @@ variable "tempo_resources" { }) default = {} } + +variable "chunk_db_size" { + type = string + description = "Shared distill-fs ChunkDB map capacity, e.g. 64GiB; empty uses the Linux default of 100 GiB. Existing caches must not be resized." + default = "" + validation { + condition = var.chunk_db_size == "" || can(regex("^[0-9]+(B|KiB|MiB|GiB|TiB)?$", var.chunk_db_size)) + error_message = "chunk_db_size must be empty, whole bytes, or an integer with B/KiB/MiB/GiB/TiB." + } +} From 374c919cdda2c91a4d25728fdb25d7c70d0e6e9a Mon Sep 17 00:00:00 2001 From: Tianyu Zhou Date: Sat, 19 Sep 2026 10:44:57 +0800 Subject: [PATCH 2/2] build: pin verified distill-fs v0.1.2 release Consume the published stripped static release with configurable ChunkDB capacity. Pin its release URL and verified archive SHA-256 together. Verify provenance, binary hash, static linking, and stripped symbols, exercise installer rejection cases, and validate custom-capacity mounts, maintenance, and recovery with sandboxd on the Linux test node. Signed-off-by: Tianyu Zhou --- builder/distill-fs-versions.env | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/builder/distill-fs-versions.env b/builder/distill-fs-versions.env index 2ef24c26..77819b84 100644 --- a/builder/distill-fs-versions.env +++ b/builder/distill-fs-versions.env @@ -3,6 +3,6 @@ # AKernel's distill-fs release dependency. Verify the published release archive # before updating its version, URL, and SHA-256 together. -DISTILL_FS_RELEASE=v0.1.1 -DISTILL_FS_AMD64_URL=https://github.com/inclusionAI/distill-fs/releases/download/v0.1.1/distill-fs-v0.1.1-linux-amd64.tar.gz -DISTILL_FS_AMD64_SHA256=b16e225e5b777f673bd98dd0968a15c190e333690356552b69a2b2624c3d5dcb +DISTILL_FS_RELEASE=v0.1.2 +DISTILL_FS_AMD64_URL=https://github.com/inclusionAI/distill-fs/releases/download/v0.1.2/distill-fs-v0.1.2-linux-amd64.tar.gz +DISTILL_FS_AMD64_SHA256=d71620f5e9a36ae08602adea76f604cc113953cb0dd9d4f134aee16f0c3f6f62