fix(chart): default containerdSocketPath to empty and bump opensandbox chart to 0.2.2

.github/workflows/kubernetes-test.yml

@@ -94,6 +94,11 @@ jobs:
         run: |
           make lint
 
+      - name: Lint Helm charts
+        working-directory: kubernetes
+        run: |
+          make helm-lint
+
       - name: Build binary
         working-directory: kubernetes
         run: |

.github/workflows/publish-helm-chart.yml

@@ -13,13 +13,17 @@ on:
           - opensandbox
           - opensandbox-node-agent
         default: 'opensandbox-controller'
+      chart_version:
+        description: 'Chart version to release (without v prefix, e.g., 0.1.0)'
+        required: true
+        default: '0.1.0'
       app_version:
         description: 'App version (without v prefix, e.g., 0.1.0)'
         required: true
         default: '0.1.0'
   push:
     tags:
-      - 'helm/**'  # Format: helm/<component>/<app_version>, e.g., helm/opensandbox-controller/0.1.0
+      - 'helm/**'  # Format: helm/<component>/<chart_version>, e.g., helm/opensandbox-controller/0.1.0
 
 jobs:
   release-preflight:
@@ -63,12 +67,13 @@ jobs:
             VERSION=${VERSION#v}
 
             echo "component=$COMPONENT" >> $GITHUB_OUTPUT
-            echo "app_version=$VERSION" >> $GITHUB_OUTPUT
+            echo "chart_version=$VERSION" >> $GITHUB_OUTPUT
             echo "release_tag=$TAG_PATH" >> $GITHUB_OUTPUT
           else
             echo "component=${{ inputs.component }}" >> $GITHUB_OUTPUT
+            echo "chart_version=${{ inputs.chart_version }}" >> $GITHUB_OUTPUT
             echo "app_version=${{ inputs.app_version }}" >> $GITHUB_OUTPUT
-            echo "release_tag=helm/${{ inputs.component }}/${{ inputs.app_version }}" >> $GITHUB_OUTPUT
+            echo "release_tag=helm/${{ inputs.component }}/${{ inputs.chart_version }}" >> $GITHUB_OUTPUT
           fi
 
       - name: Verify release tag on origin
@@ -120,10 +125,18 @@ jobs:
         run: |
           CHART_PATH="${{ steps.chart_path.outputs.path }}"
           CHART_VERSION=$(grep '^version:' $CHART_PATH/Chart.yaml | awk '{print $2}')
+          EXPECTED_CHART_VERSION="${{ steps.parse_tag.outputs.chart_version }}"
+
+          if [ "$CHART_VERSION" != "$EXPECTED_CHART_VERSION" ]; then
+            echo "::error::Chart.yaml version '$CHART_VERSION' does not match requested chart version '$EXPECTED_CHART_VERSION'."
+            exit 1
+          fi
+
           echo "version=$CHART_VERSION" >> $GITHUB_OUTPUT
-          echo "Chart version: $CHART_VERSION"
+          echo "Verified chart version: $CHART_VERSION"
 
-      - name: Update Chart.yaml with app version
+      - name: Update Chart.yaml with app version for manual release
+        if: ${{ github.event_name == 'workflow_dispatch' }}
         run: |
           APP_VERSION="${{ steps.parse_tag.outputs.app_version }}"
           CHART_PATH="${{ steps.chart_path.outputs.path }}"
@@ -134,6 +147,14 @@ jobs:
           echo "Updated Chart.yaml:"
           cat $CHART_PATH/Chart.yaml
 
+      - name: Get app version from Chart.yaml
+        id: app_version
+        run: |
+          CHART_PATH="${{ steps.chart_path.outputs.path }}"
+          APP_VERSION=$(grep '^appVersion:' $CHART_PATH/Chart.yaml | awk '{print $2}' | tr -d '"')
+          echo "version=$APP_VERSION" >> $GITHUB_OUTPUT
+          echo "App version: $APP_VERSION"
+
       - name: Build dependencies (for opensandbox all-in-one chart)
         if: ${{ steps.parse_tag.outputs.component == 'opensandbox' }}
         run: |
@@ -160,12 +181,12 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ steps.parse_tag.outputs.release_tag }}
-          name: Helm Chart ${{ steps.parse_tag.outputs.component }} ${{ steps.chart_version.outputs.version }} (App v${{ steps.parse_tag.outputs.app_version }})
+          name: Helm Chart ${{ steps.parse_tag.outputs.component }} ${{ steps.chart_version.outputs.version }} (App v${{ steps.app_version.outputs.version }})
           body: |
             ## ${{ steps.parse_tag.outputs.component }} Helm Chart
 
             **Chart Version:** ${{ steps.chart_version.outputs.version }}
-            **App Version:** ${{ steps.parse_tag.outputs.app_version }}
+            **App Version:** ${{ steps.app_version.outputs.version }}
 
             ### Installation
 
@@ -195,7 +216,7 @@ jobs:
             ### What's Changed
 
             - Chart version: ${{ steps.chart_version.outputs.version }}
-            - App version: ${{ steps.parse_tag.outputs.app_version }}
+            - App version: ${{ steps.app_version.outputs.version }}
           files: |
             ${{ steps.parse_tag.outputs.component }}-*.tgz
           draft: false

docs/examples/aks-kata.md

@@ -130,7 +130,7 @@ kubectl rollout status deploy/opensandbox-controller-manager \
 ```
 
 ::: tip
-This example clears `controller.snapshot.containerdSocketPath` because the pinned controller image (`controller:v0.2.0`) does not accept the `--containerd-socket-path` flag. Current controller builds **do** accept it (see [`kubernetes/cmd/controller/main.go`](https://github.com/opensandbox-group/OpenSandbox/blob/main/kubernetes/cmd/controller/main.go)); if your nodes use a non-default containerd socket and you deploy a controller image that supports the flag, set this value accordingly.
+`controller.snapshot.containerdSocketPath` defaults to `""` in the chart, which allows the controller to use its built-in default (`/var/run/containerd/containerd.sock`) without passing the `--containerd-socket-path` flag unless explicitly configured. If your nodes use a non-default containerd socket and you deploy a controller image that supports the flag, set this value accordingly.
 :::
 
 ## 5. Use `main.py`

docs/kubernetes/deployment.md

@@ -26,13 +26,13 @@ Install the controller and CRDs before the lifecycle server. The server runs in
 Choose a published `opensandbox-server` chart from [GitHub Releases](https://github.com/opensandbox-group/OpenSandbox/releases?q=helm%2Fopensandbox-server&expanded=true), then set both versions from that release:
 
 ```sh
-APP_VERSION="<app-version>"
 CHART_VERSION="<chart-version>"
-CHART_URL="https://github.com/opensandbox-group/OpenSandbox/releases/download/helm/opensandbox-server/${APP_VERSION}/opensandbox-server-${CHART_VERSION}.tgz"
+APP_VERSION="<app-version>"
+CHART_URL="https://github.com/opensandbox-group/OpenSandbox/releases/download/helm/opensandbox-server/${CHART_VERSION}/opensandbox-server-${CHART_VERSION}.tgz"
 ```
 
 ::: info Versioning
-The release tag identifies the server application version, while the `.tgz` filename uses the Helm chart version. These versions are independent and are listed on each GitHub Release.
+The release tag and `.tgz` filename identify the Helm chart version. The server application version is independent and is listed on each GitHub Release.
 :::
 
 ### Configure API authentication

kubernetes/Makefile

@@ -530,9 +530,13 @@ HELM_CHART_PATH ?= charts/opensandbox-controller
 HELM_CHART_VERSION ?= $(VERSION)
 
 .PHONY: helm-lint
-helm-lint: ## Lint the Helm chart
-	@echo "Linting Helm chart..."
-	helm lint $(HELM_CHART_PATH)
+helm-lint: ## Lint all Helm charts and verify dependencies
+	@echo "Linting Helm charts..."
+	helm lint charts/opensandbox-controller
+	helm lint charts/opensandbox-server
+	helm lint charts/opensandbox-node-agent
+	helm dependency build charts/opensandbox
+	helm lint charts/opensandbox
 
 .PHONY: helm-template
 helm-template: ## Generate Kubernetes manifests from Helm chart

kubernetes/charts/opensandbox-controller/Chart.yaml

@@ -2,7 +2,7 @@ apiVersion: v2
 name: opensandbox-controller
 description: A Kubernetes operator for managing sandbox environments with resource pooling and batch delivery
 type: application
-version: 0.2.0
+version: 0.2.1
 appVersion: "0.2.0"
 
 keywords:

kubernetes/charts/opensandbox-controller/values.yaml

@@ -62,8 +62,8 @@ controller:
     imageCommitterImage: "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/image-committer:v0.1.1"
     # -- PodTemplateSpec overlay for image-committer commit Job Pods.
     imageCommitterPodTemplate: {}
-    # -- Containerd socket path of host
-    containerdSocketPath: "/var/run/containerd/containerd.sock"
+    # -- Containerd socket path of host. Defaults to empty so the controller uses its built-in default (/var/run/containerd/containerd.sock) without passing --containerd-socket-path flag.
+    containerdSocketPath: ""
     # -- Timeout duration for commit jobs
     commitJobTimeout: "10m"
     # -- OCI registry prefix used for snapshot images.

kubernetes/charts/opensandbox-server/Chart.yaml

@@ -17,7 +17,7 @@ name: opensandbox-server
 description: OpenSandbox Lifecycle API server for sandbox creation and management
 type: application
 version: 0.1.0
-appVersion: "0.1.0"
+appVersion: "0.2.2"
 # execd bootstrap.sh installed to /opt/opensandbox (flattened from /opt/opensandbox/bin)
 
 keywords:

kubernetes/charts/opensandbox-server/README.md

@@ -11,12 +11,12 @@ OpenSandbox Lifecycle API server: provides sandbox create/delete and other lifec
 
 ## Install from a GitHub Release
 
-Choose a published `opensandbox-server` chart from [GitHub Releases](https://github.com/opensandbox-group/OpenSandbox/releases?q=helm%2Fopensandbox-server&expanded=true). The release tag uses the application version, while the package filename uses the chart version shown in the release notes.
+Choose a published `opensandbox-server` chart from [GitHub Releases](https://github.com/opensandbox-group/OpenSandbox/releases?q=helm%2Fopensandbox-server&expanded=true). The release tag and package filename use the chart version shown in the release notes; the application version is listed separately.
 
 ```bash
-APP_VERSION="<app-version>"
 CHART_VERSION="<chart-version>"
-CHART_URL="https://github.com/opensandbox-group/OpenSandbox/releases/download/helm/opensandbox-server/${APP_VERSION}/opensandbox-server-${CHART_VERSION}.tgz"
+APP_VERSION="<app-version>"
+CHART_URL="https://github.com/opensandbox-group/OpenSandbox/releases/download/helm/opensandbox-server/${CHART_VERSION}/opensandbox-server-${CHART_VERSION}.tgz"
 
 helm show values "${CHART_URL}"
 ```

kubernetes/charts/opensandbox/Chart.lock

@@ -1,12 +1,12 @@
 dependencies:
 - name: opensandbox-controller
   repository: file://../opensandbox-controller
-  version: 0.2.0
+  version: 0.2.1
 - name: opensandbox-server
   repository: file://../opensandbox-server
   version: 0.1.0
 - name: opensandbox-node-agent
   repository: file://../opensandbox-node-agent
   version: 0.1.0
-digest: sha256:18ed87f3960e0df808eba7bd27455e416dc6330951281493bba4bb0ab0321512
-generated: "2026-07-30T14:58:20.116343+08:00"
+digest: sha256:9a8dfea166e50e4016bd850366a17e02a9052cb73f88375d934558c625dfb956
+generated: "2026-08-18T18:20:43.341958+08:00"

kubernetes/charts/opensandbox/Chart.yaml

@@ -16,8 +16,8 @@ apiVersion: v2
 name: opensandbox
 description: All-in-one Helm chart for deploying OpenSandbox controller and server
 type: application
-version: 0.2.0
-appVersion: "0.2.0"
+version: 0.2.2
+appVersion: "0.2.2"
 
 keywords:
   - sandbox
@@ -40,7 +40,7 @@ kubeVersion: ">=1.21.1-0"
 
 dependencies:
   - name: opensandbox-controller
-    version: "0.2.0"
+    version: "0.2.1"
     repository: "file://../opensandbox-controller"
   - name: opensandbox-server
     version: "0.1.0"

kubernetes/docs/HELM-DEPLOYMENT.md

@@ -446,20 +446,20 @@ Tag naming convention: `helm/{component}/{version}`
 
 This automatically triggers the workflow to:
 1. Parse the tag to extract component and version
-2. Update the version in the corresponding Chart.yaml
-3. Package the Helm Chart
-4. Create a GitHub Release
-5. Publish the .tgz package to the Release
+2. Verify the tag version matches the chart `version`
+3. Preserve the committed chart `appVersion`
+4. Package the Helm Chart
+5. Create a GitHub Release and publish the .tgz package
 
 Important versioning note:
 
 - The Helm chart `version` is the chart package version and is released through
   `helm/{component}/{version}` tags.
 - The chart `appVersion` is the default image/application version used by that
   chart release.
-- The `publish-helm-chart.yml` workflow updates `appVersion` for the published
-  release, but intentionally does not auto-bump the chart `version` inside
-  `Chart.yaml` on server release branches.
+- Tag-triggered publishing preserves the committed chart `appVersion` and
+  verifies that the tag matches the committed chart `version`. Manual runs can
+  override `appVersion` independently.
 - If you need a specific server image release, set the image tag explicitly
   (for example `--set server.image.tag=v0.1.13`) or publish a new Helm chart
   package version for the chart itself.