From 485048eba767ed82b48e3a0f0140da8386476cca Mon Sep 17 00:00:00 2001 From: "pingshan.wj" Date: Wed, 11 Feb 2026 21:00:29 +0800 Subject: [PATCH 1/3] build(k8s): add k8s related components image build --- .github/workflows/publish-components.yml | 17 +++ kubernetes/build.sh | 77 +++++++++++ kubernetes/docs/BUILD-IMAGES.md | 156 +++++++++++++++++++++++ 3 files changed, 250 insertions(+) create mode 100755 kubernetes/build.sh create mode 100644 kubernetes/docs/BUILD-IMAGES.md diff --git a/.github/workflows/publish-components.yml b/.github/workflows/publish-components.yml index 0aa6c47f..570714c7 100644 --- a/.github/workflows/publish-components.yml +++ b/.github/workflows/publish-components.yml @@ -15,6 +15,8 @@ on: - code-interpreter - ingress - egress + - controller + - task-executor default: 'execd' image_tag: description: 'Docker image tag' @@ -26,6 +28,8 @@ on: - 'docker/code-interpreter/**' - 'docker/ingress/**' - 'docker/egress/**' + - 'k8s/controller/**' + - 'k8s/task-executor/**' jobs: publish: @@ -63,6 +67,15 @@ jobs: COMPONENT=$(echo "$TAG_PATH" | cut -d'/' -f2) IMAGE_TAG=$(echo "$TAG_PATH" | cut -d'/' -f3) + echo "component=$COMPONENT" >> $GITHUB_OUTPUT + echo "image_tag=$IMAGE_TAG" >> $GITHUB_OUTPUT + elif [[ "${{ github.ref }}" == refs/tags/k8s/* ]]; then + TAG_PATH="${{ github.ref }}" + TAG_PATH="${TAG_PATH#refs/tags/}" + + COMPONENT=$(echo "$TAG_PATH" | cut -d'/' -f2) + IMAGE_TAG=$(echo "$TAG_PATH" | cut -d'/' -f3) + echo "component=$COMPONENT" >> $GITHUB_OUTPUT echo "image_tag=$IMAGE_TAG" >> $GITHUB_OUTPUT else @@ -88,6 +101,10 @@ jobs: cd components/ingress elif [ "$COMPONENT" == "egress" ]; then cd components/egress + elif [ "$COMPONENT" == "controller" ]; then + cd kubernetes + elif [ "$COMPONENT" == "task-executor" ]; then + cd kubernetes else cd sandboxes/$COMPONENT fi diff --git a/kubernetes/build.sh b/kubernetes/build.sh new file mode 100755 index 00000000..ccbaf59f --- /dev/null +++ b/kubernetes/build.sh @@ -0,0 +1,77 @@ +#!/bin/bash +# Copyright 2025 Alibaba Group Holding Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +set -e + +# Default values +TAG=${TAG:-latest} +COMPONENT=${COMPONENT:-controller} +PUSH=${PUSH:-true} + +# Image repository +ACR_REPO="sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox" + +# Component specific settings +if [ "$COMPONENT" == "controller" ]; then + IMAGE_NAME="controller" + BUILD_ARG="--build-arg PACKAGE=cmd/controller/main.go" +elif [ "$COMPONENT" == "task-executor" ]; then + IMAGE_NAME="task-executor" + BUILD_ARG="--build-arg PACKAGE=cmd/task-executor/main.go" +else + echo "Error: Unknown component: $COMPONENT" + echo "Available components: controller, task-executor" + exit 1 +fi + +echo "=========================================" +echo "Building $COMPONENT" +echo "Image: $IMAGE_NAME" +echo "Tag: $TAG" +echo "Push: $PUSH" +echo "=========================================" + +# Build for multiple platforms +PLATFORMS="linux/amd64,linux/arm64" + +if [ "$PUSH" == "true" ]; then + # Build and push to ACR registry + docker buildx build \ + --platform $PLATFORMS \ + $BUILD_ARG \ + -t ${ACR_REPO}/${IMAGE_NAME}:${TAG} \ + --push \ + -f Dockerfile \ + . + + echo "=========================================" + echo "Successfully built and pushed:" + echo " ${ACR_REPO}/${IMAGE_NAME}:${TAG}" + echo "=========================================" +else + # Build only (for local testing) + docker buildx build \ + --platform linux/amd64 \ + $BUILD_ARG \ + -t ${IMAGE_NAME}:${TAG} \ + -f Dockerfile \ + --load \ + . + + echo "=========================================" + echo "Successfully built (local only):" + echo " ${IMAGE_NAME}:${TAG}" + echo "=========================================" +fi diff --git a/kubernetes/docs/BUILD-IMAGES.md b/kubernetes/docs/BUILD-IMAGES.md new file mode 100644 index 00000000..4d419da2 --- /dev/null +++ b/kubernetes/docs/BUILD-IMAGES.md @@ -0,0 +1,156 @@ +# 镜像构建指南 + +本文档介绍如何构建 OpenSandbox Kubernetes Controller 和 Task Executor 镜像。 + +## 方式一: 使用构建脚本（推荐） + +### 本地构建 + +```bash +cd kubernetes + +# 构建 controller 镜像 +COMPONENT=controller TAG=v0.1.0 PUSH=false ./build.sh + +# 构建 task-executor 镜像 +COMPONENT=task-executor TAG=v0.1.0 PUSH=false ./build.sh +``` + +### 构建并推送到镜像仓库 + +```bash +# 确保已登录阿里云 ACR +docker login sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com + +# 构建并推送 controller 镜像 +COMPONENT=controller TAG=v0.1.0 ./build.sh + +# 构建并推送 task-executor 镜像 +COMPONENT=task-executor TAG=v0.1.0 ./build.sh +``` + +### 环境变量说明 + +- `COMPONENT`: 要构建的组件，可选值: `controller`, `task-executor` +- `TAG`: 镜像标签，默认为 `latest` +- `PUSH`: 是否推送到远程仓库，默认为 `true` + +## 方式二: 使用 GitHub Actions + +### 手动触发工作流 + +1. 打开 [Actions 页面](https://github.com/alibaba/OpenSandbox/actions) +2. 选择 "Publish Components Image" 工作流 +3. 点击 "Run workflow" +4. 选择组件和镜像标签: + - Component: 在下拉菜单中选择组件名称 + - Controller: `controller` + - Task Executor: `task-executor` + - Image tag: 输入镜像标签，例如 `v0.1.0` +5. 点击 "Run workflow" 开始构建 + +### 通过 Git Tag 触发（推荐） + +创建带有特定前缀的 tag 即可自动触发构建: + +```bash +# 构建 controller v0.1.0 +git tag k8s/controller/v0.1.0 +git push origin k8s/controller/v0.1.0 + +# 构建 task-executor v0.1.0 +git tag k8s/task-executor/v0.1.0 +git push origin k8s/task-executor/v0.1.0 +``` + +**Tag 命名规则**: `k8s//` +- ``: 组件名称 `controller` 或 `task-executor` +- ``: 版本号，例如 `v0.1.0` +- ``: 镜像版本号，例如 `v0.1.0` + +## 方式三: 使用 Makefile + +```bash +cd kubernetes + +# 构建 controller 镜像（仅本地） +make docker-build IMG=myregistry/opensandbox-controller:v0.1.0 + +# 构建 task-executor 镜像（仅本地） +make docker-build-task-executor TASK_EXECUTOR_IMG=myregistry/opensandbox-task-executor:v0.1.0 + +# 推送镜像 +make docker-push IMG=myregistry/opensandbox-controller:v0.1.0 +make docker-push-task-executor TASK_EXECUTOR_IMG=myregistry/opensandbox-task-executor:v0.1.0 +``` + +## 镜像仓库 + +构建的镜像会推送到以下仓库: + +### 阿里云容器镜像服务 (ACR) +- Controller: `sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/controller:` +- Task Executor: `sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/task-executor:` + +## 多架构支持 + +构建脚本默认支持以下架构: +- `linux/amd64` +- `linux/arm64` + +如需构建其他架构，请修改 `build.sh` 中的 `PLATFORMS` 变量。 + +## 本地测试 + +如果只想在本地测试镜像而不推送: + +```bash +# 构建本地镜像 +COMPONENT=controller TAG=test PUSH=false ./build.sh + +# 加载到 kind 集群测试 +kind load docker-image opensandbox-controller:test + +# 或加载到 minikube 测试 +minikube image load opensandbox-controller:test +``` + +## 故障排查 + +### 权限问题 + +如果遇到 Docker 权限问题: +```bash +sudo usermod -aG docker $USER +newgrp docker +``` + +### Buildx 不可用 + +确保启用 Docker Buildx: +```bash +docker buildx create --use +docker buildx inspect --bootstrap +``` + +### 磁盘空间不足 + +清理 Docker 缓存: +```bash +docker system prune -a +docker builder prune -a +``` + +## 配置私有镜像仓库 + +如需使用自己的镜像仓库，修改 `build.sh` 中的仓库地址: + +```bash +# 编辑 build.sh +ACR_REPO="your-acr-registry.cr.aliyuncs.com/your-namespace" +``` + +或者直接在构建时使用环境变量: +```bash +ACR_REPO=myregistry.com/myrepo COMPONENT=controller TAG=v0.1.0 ./build.sh +``` From acbc50b369aeac401f97318d71c443631df66b93 Mon Sep 17 00:00:00 2001 From: "pingshan.wj" Date: Wed, 11 Feb 2026 21:01:05 +0800 Subject: [PATCH 2/3] build(k8s): add k8s helm chart --- .github/workflows/publish-helm-chart.yml | 128 +++++ kubernetes/Makefile | 84 ++- .../charts/opensandbox-controller/.helmignore | 27 + .../charts/opensandbox-controller/Chart.yaml | 44 ++ .../charts/opensandbox-controller/README.md | 228 ++++++++ .../templates/NOTES.txt | 96 ++++ .../templates/_helpers.tpl | 114 ++++ .../templates/clusterrole.yaml | 106 ++++ .../templates/clusterrolebinding.yaml | 39 ++ .../templates/crds/batchsandboxes.yaml | 196 +++++++ .../templates/crds/pools.yaml | 136 +++++ .../templates/deployment.yaml | 114 ++++ .../templates/namespace.yaml | 7 + .../templates/serviceaccount.yaml | 18 + .../charts/opensandbox-controller/values.yaml | 163 ++++++ kubernetes/docs/HELM-DEPLOYMENT.md | 504 ++++++++++++++++++ 16 files changed, 2003 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/publish-helm-chart.yml create mode 100644 kubernetes/charts/opensandbox-controller/.helmignore create mode 100644 kubernetes/charts/opensandbox-controller/Chart.yaml create mode 100644 kubernetes/charts/opensandbox-controller/README.md create mode 100644 kubernetes/charts/opensandbox-controller/templates/NOTES.txt create mode 100644 kubernetes/charts/opensandbox-controller/templates/_helpers.tpl create mode 100644 kubernetes/charts/opensandbox-controller/templates/clusterrole.yaml create mode 100644 kubernetes/charts/opensandbox-controller/templates/clusterrolebinding.yaml create mode 100644 kubernetes/charts/opensandbox-controller/templates/crds/batchsandboxes.yaml create mode 100644 kubernetes/charts/opensandbox-controller/templates/crds/pools.yaml create mode 100644 kubernetes/charts/opensandbox-controller/templates/deployment.yaml create mode 100644 kubernetes/charts/opensandbox-controller/templates/namespace.yaml create mode 100644 kubernetes/charts/opensandbox-controller/templates/serviceaccount.yaml create mode 100644 kubernetes/charts/opensandbox-controller/values.yaml create mode 100644 kubernetes/docs/HELM-DEPLOYMENT.md diff --git a/.github/workflows/publish-helm-chart.yml b/.github/workflows/publish-helm-chart.yml new file mode 100644 index 00000000..27a0ddfa --- /dev/null +++ b/.github/workflows/publish-helm-chart.yml @@ -0,0 +1,128 @@ +name: Publish Helm Chart + +on: + workflow_dispatch: + inputs: + component: + description: 'Component to release' + required: true + type: choice + options: + - opensandbox-controller + default: 'opensandbox-controller' + chart_version: + description: 'Chart version to release' + required: true + default: '0.1.0' + app_version: + description: 'App version' + required: true + default: '0.0.1' + push: + tags: + - 'helm/**' + +jobs: + publish: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Configure Git + run: | + git config user.name "$GITHUB_ACTOR" + git config user.email "$GITHUB_ACTOR@users.noreply.github.com" + + - name: Install Helm + uses: azure/setup-helm@v4 + with: + version: 'latest' + + - name: Parse tag and set variables + id: parse_tag + run: | + if [[ "${{ github.ref }}" == refs/tags/helm/* ]]; then + TAG_PATH="${{ github.ref }}" + TAG_PATH="${TAG_PATH#refs/tags/}" + + COMPONENT=$(echo "$TAG_PATH" | cut -d'/' -f2) + VERSION=$(echo "$TAG_PATH" | cut -d'/' -f3) + + echo "component=$COMPONENT" >> $GITHUB_OUTPUT + echo "chart_version=$VERSION" >> $GITHUB_OUTPUT + echo "app_version=$VERSION" >> $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 + fi + + - name: Set chart path + id: chart_path + run: | + COMPONENT="${{ steps.parse_tag.outputs.component }}" + + if [ "$COMPONENT" == "opensandbox-controller" ]; then + CHART_PATH="kubernetes/charts/opensandbox-controller" + else + echo "Error: Unknown component: $COMPONENT" + exit 1 + fi + + echo "path=$CHART_PATH" >> $GITHUB_OUTPUT + + - name: Update Chart.yaml with versions + run: | + CHART_VERSION="${{ steps.parse_tag.outputs.chart_version }}" + APP_VERSION="${{ steps.parse_tag.outputs.app_version }}" + CHART_PATH="${{ steps.chart_path.outputs.path }}" + + sed -i "s/^version:.*/version: $CHART_VERSION/" $CHART_PATH/Chart.yaml + sed -i "s/^appVersion:.*/appVersion: \"$APP_VERSION\"/" $CHART_PATH/Chart.yaml + + echo "Updated Chart.yaml:" + cat $CHART_PATH/Chart.yaml + + - name: Lint Helm chart + run: | + CHART_PATH="${{ steps.chart_path.outputs.path }}" + helm lint $CHART_PATH + + - name: Package Helm chart + run: | + CHART_PATH="${{ steps.chart_path.outputs.path }}" + helm package $CHART_PATH + + - name: Create GitHub Release + uses: softprops/action-gh-release@v1 + with: + tag_name: helm/${{ steps.parse_tag.outputs.component }}/${{ steps.parse_tag.outputs.chart_version }} + name: Helm Chart ${{ steps.parse_tag.outputs.component }} v${{ steps.parse_tag.outputs.chart_version }} + body: | + ## ${{ steps.parse_tag.outputs.component }} Helm Chart v${{ steps.parse_tag.outputs.chart_version }} + + **App Version:** ${{ steps.parse_tag.outputs.app_version }} + + ### Installation + + 直接从 Release 安装: + + ```bash + helm install ${{ steps.parse_tag.outputs.component }} https://github.com/${{ github.repository }}/releases/download/helm/${{ steps.parse_tag.outputs.component }}/${{ steps.parse_tag.outputs.chart_version }}/${{ steps.parse_tag.outputs.component }}-${{ steps.parse_tag.outputs.chart_version }}.tgz --namespace opensandbox-system --create-namespace + ``` + + ### What's Changed + + - Chart version: ${{ steps.parse_tag.outputs.chart_version }} + - App version: ${{ steps.parse_tag.outputs.app_version }} + files: | + ${{ steps.parse_tag.outputs.component }}-*.tgz + draft: false + prerelease: false + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/kubernetes/Makefile b/kubernetes/Makefile index 2c22fe9b..c94c6224 100644 --- a/kubernetes/Makefile +++ b/kubernetes/Makefile @@ -412,4 +412,86 @@ catalog-build: opm ## Build a catalog image. # Push the catalog image. .PHONY: catalog-push catalog-push: ## Push a catalog image. - $(MAKE) docker-push IMG=$(CATALOG_IMG) \ No newline at end of file + $(MAKE) docker-push IMG=$(CATALOG_IMG) + +##@ Helm + +# Helm chart configuration +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) + +.PHONY: helm-template +helm-template: ## Generate Kubernetes manifests from Helm chart + @echo "Generating manifests from Helm chart..." + helm template opensandbox $(HELM_CHART_PATH) \ + --set controller.image.repository=$(IMAGE_TAG_BASE) \ + --set controller.image.tag=$(VERSION) + +.PHONY: helm-template-debug +helm-template-debug: ## Generate Kubernetes manifests with debug output + @echo "Generating manifests from Helm chart with debug..." + helm template opensandbox $(HELM_CHART_PATH) \ + --set controller.image.repository=$(IMAGE_TAG_BASE) \ + --set controller.image.tag=$(VERSION) \ + --debug + +.PHONY: helm-package +helm-package: ## Package the Helm chart + @echo "Packaging Helm chart..." + @mkdir -p dist + helm package $(HELM_CHART_PATH) -d dist/ --version $(HELM_CHART_VERSION) --app-version $(VERSION) + +.PHONY: helm-install +helm-install: ## Install the Helm chart + @echo "Installing Helm chart..." + helm install opensandbox $(HELM_CHART_PATH) \ + --set controller.image.repository=$(IMAGE_TAG_BASE) \ + --set controller.image.tag=$(VERSION) \ + --namespace opensandbox-system \ + --create-namespace + +.PHONY: helm-upgrade +helm-upgrade: ## Upgrade the Helm chart + @echo "Upgrading Helm chart..." + helm upgrade opensandbox $(HELM_CHART_PATH) \ + --set controller.image.repository=$(IMAGE_TAG_BASE) \ + --set controller.image.tag=$(VERSION) \ + --namespace opensandbox-system + +.PHONY: helm-uninstall +helm-uninstall: ## Uninstall the Helm chart + @echo "Uninstalling Helm chart..." + helm uninstall opensandbox --namespace opensandbox-system + +.PHONY: helm-test +helm-test: ## Run Helm chart tests + @echo "Running Helm chart tests..." + helm test opensandbox --namespace opensandbox-system + +.PHONY: helm-docs +helm-docs: ## Generate Helm chart documentation (requires helm-docs) + @if command -v helm-docs >/dev/null 2>&1; then \ + echo "Generating Helm chart documentation..."; \ + helm-docs $(HELM_CHART_PATH); \ + else \ + echo "helm-docs is not installed. Install it with: go install github.com/norwoodj/helm-docs/cmd/helm-docs@latest"; \ + exit 1; \ + fi + +.PHONY: helm-dry-run +helm-dry-run: ## Perform a dry-run install of the Helm chart + @echo "Performing dry-run installation..." + helm install opensandbox $(HELM_CHART_PATH) \ + --set controller.image.repository=$(IMAGE_TAG_BASE) \ + --set controller.image.tag=$(VERSION) \ + --namespace opensandbox-system \ + --create-namespace \ + --dry-run --debug + +.PHONY: helm-all +helm-all: helm-lint helm-package ## Run all Helm-related tasks (lint and package) \ No newline at end of file diff --git a/kubernetes/charts/opensandbox-controller/.helmignore b/kubernetes/charts/opensandbox-controller/.helmignore new file mode 100644 index 00000000..10a41c72 --- /dev/null +++ b/kubernetes/charts/opensandbox-controller/.helmignore @@ -0,0 +1,27 @@ +# Patterns to ignore when building packages. +# This supports shell glob matching, relative path matching, and +# negation (prefixed with !). Only one pattern per line. +.DS_Store +# Common VCS dirs +.git/ +.gitignore +.bzr/ +.bzrignore +.hg/ +.hgignore +.svn/ +# Common backup files +*.swp +*.bak +*.tmp +*.orig +*~ +# Various IDEs +.project +.idea/ +*.tmproj +.vscode/ +# OWNERS file +OWNERS +# Make files +Makefile diff --git a/kubernetes/charts/opensandbox-controller/Chart.yaml b/kubernetes/charts/opensandbox-controller/Chart.yaml new file mode 100644 index 00000000..c362a955 --- /dev/null +++ b/kubernetes/charts/opensandbox-controller/Chart.yaml @@ -0,0 +1,44 @@ +apiVersion: v2 +name: opensandbox-controller +description: A Kubernetes operator for managing sandbox environments with resource pooling and batch delivery +type: application +version: 0.1.0 +appVersion: "0.0.1" + +keywords: + - sandbox + - kubernetes + - operator + - resource-pool + - batch-sandbox + - task-orchestration + +home: https://github.com/alibaba/OpenSandbox +sources: + - https://github.com/alibaba/OpenSandbox/tree/main/kubernetes + +maintainers: + - name: OpenSandbox Team + email: opensandbox@example.com + +icon: https://raw.githubusercontent.com/alibaba/OpenSandbox/main/kubernetes/images/logo.png + +# Kubernetes version constraints +kubeVersion: ">=1.22.4-0" + +annotations: + # Category for Artifact Hub + artifacthub.io/category: integration-delivery + artifacthub.io/license: Apache-2.0 + artifacthub.io/signKey: | + fingerprint: [your-gpg-fingerprint] + artifacthub.io/prerelease: "false" + artifacthub.io/operator: "true" + artifacthub.io/operatorCapabilities: Full Lifecycle + artifacthub.io/recommendations: | + - url: https://github.com/kubernetes-sigs/kind + artifacthub.io/links: | + - name: Documentation + url: https://github.com/alibaba/OpenSandbox/blob/main/kubernetes/README.md + - name: Support + url: https://github.com/alibaba/OpenSandbox/issues diff --git a/kubernetes/charts/opensandbox-controller/README.md b/kubernetes/charts/opensandbox-controller/README.md new file mode 100644 index 00000000..65660ef0 --- /dev/null +++ b/kubernetes/charts/opensandbox-controller/README.md @@ -0,0 +1,228 @@ +# OpenSandbox Controller Helm Chart + +A Helm chart for deploying the OpenSandbox Kubernetes Controller, which manages sandbox environments with resource pooling and batch delivery capabilities. + +## Introduction + +This chart bootstraps an OpenSandbox Controller deployment on a Kubernetes cluster using the Helm package manager. The controller provides: + +- **Batch Sandbox Management**: Create and manage multiple identical sandbox environments +- **Resource Pooling**: Maintain pre-warmed resource pools for rapid sandbox provisioning +- **Task Orchestration**: Optional task execution within sandboxes +- **High Performance**: O(1) time complexity for batch sandbox delivery + +## Prerequisites + +- Kubernetes 1.22.4+ +- Helm 3.0+ +- Container runtime (Docker, containerd, etc.) + +## Installing the Chart + +To install the chart with the release name `opensandbox`: + +```bash +helm install opensandbox ./opensandbox-controller \ + --set controller.image.repository=/opensandbox-controller \ + --set controller.image.tag=v0.0.1 \ + --namespace opensandbox-system \ + --create-namespace +``` + +The command deploys OpenSandbox Controller on the Kubernetes cluster with default configuration. The [Parameters](#parameters) section lists the parameters that can be configured during installation. + +## Uninstalling the Chart + +To uninstall/delete the `opensandbox` deployment: + +```bash +helm delete opensandbox -n opensandbox-system +``` + +The command removes all the Kubernetes components associated with the chart. Note that CRDs are kept by default (can be changed via `crds.keep`). + +To also remove the CRDs: + +```bash +kubectl delete crd batchsandboxes.sandbox.opensandbox.io +kubectl delete crd pools.sandbox.opensandbox.io +``` + +## Parameters + +### Global Parameters + +| Name | Description | Value | +|------|-------------|-------| +| `nameOverride` | Override the name of the chart | `""` | +| `fullnameOverride` | Override the full name of the chart | `""` | +| `namespaceOverride` | Override the namespace where resources will be created | `""` | + +### Controller Parameters + +| Name | Description | Value | +|------|-------------|-------| +| `controller.image.repository` | Controller image repository | `opensandbox.io/opensandbox-controller` | +| `controller.image.pullPolicy` | Image pull policy | `IfNotPresent` | +| `controller.image.tag` | Overrides the image tag (default is chart appVersion) | `""` | +| `controller.replicaCount` | Number of controller replicas | `1` | +| `controller.resources.limits.cpu` | CPU resource limits | `500m` | +| `controller.resources.limits.memory` | Memory resource limits | `128Mi` | +| `controller.resources.requests.cpu` | CPU resource requests | `10m` | +| `controller.resources.requests.memory` | Memory resource requests | `64Mi` | +| `controller.logLevel` | Log level (0-5, higher is more verbose) | `3` | +| `controller.leaderElection.enabled` | Enable leader election | `true` | +| `controller.batchSandboxConcurrency` | Batch sandbox controller concurrency | `32` | +| `controller.poolConcurrency` | Pool controller concurrency | `1` | +| `controller.nodeSelector` | Node labels for pod assignment | `{}` | +| `controller.tolerations` | Tolerations for pod assignment | `[]` | +| `controller.affinity` | Affinity for pod assignment | `{}` | +| `controller.podLabels` | Additional labels for controller pods | `{}` | +| `controller.podAnnotations` | Additional annotations for controller pods | `{}` | +| `controller.priorityClassName` | Priority class name for controller pods | `""` | + +### RBAC Parameters + +| Name | Description | Value | +|------|-------------|-------| +| `rbac.create` | Specifies whether RBAC resources should be created | `true` | +| `serviceAccount.create` | Specifies whether a service account should be created | `true` | +| `serviceAccount.annotations` | Annotations to add to the service account | `{}` | +| `serviceAccount.name` | The name of the service account to use | `""` | + +### CRD Parameters + +| Name | Description | Value | +|------|-------------|-------| +| `crds.install` | Specifies whether CRDs should be installed | `true` | +| `crds.keep` | Keep CRDs on chart uninstall | `true` | +| `crds.annotations` | Annotations to add to CRDs | `{"helm.sh/resource-policy": "keep"}` | + +### Additional Parameters + +| Name | Description | Value | +|------|-------------|-------| +| `imagePullSecrets` | Image pull secrets for private registries | `[]` | +| `extraEnv` | Additional environment variables | `[]` | +| `extraVolumes` | Additional volumes | `[]` | +| `extraVolumeMounts` | Additional volume mounts | `[]` | +| `extraInitContainers` | Additional init containers | `[]` | +| `extraContainers` | Additional sidecar containers | `[]` | + +## Configuration Examples + +### Custom Resource Limits + +```yaml +controller: + resources: + limits: + cpu: 1000m + memory: 512Mi + requests: + cpu: 100m + memory: 128Mi +``` + +### Use Private Registry + +```yaml +controller: + image: + repository: myregistry.example.com/opensandbox-controller + tag: v0.1.0 + +imagePullSecrets: + - name: myregistrykey +``` + +### Node Affinity + +```yaml +controller: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: node-role.kubernetes.io/control-plane + operator: Exists +``` + +## Usage Examples + +After installation, you can create resources: + +### Create a Resource Pool + +```yaml +apiVersion: sandbox.opensandbox.io/v1alpha1 +kind: Pool +metadata: + name: example-pool +spec: + template: + spec: + containers: + - name: sandbox-container + image: nginx:latest + ports: + - containerPort: 80 + capacitySpec: + bufferMax: 10 + bufferMin: 2 + poolMax: 20 + poolMin: 5 +``` + +### Create a Batch Sandbox + +```yaml +apiVersion: sandbox.opensandbox.io/v1alpha1 +kind: BatchSandbox +metadata: + name: example-batch-sandbox +spec: + replicas: 3 + poolRef: example-pool +``` + +## Upgrading + +To upgrade the chart: + +```bash +helm upgrade opensandbox ./opensandbox-controller \ + --namespace opensandbox-system \ + -f custom-values.yaml +``` + +## Troubleshooting + +### Check controller logs + +```bash +kubectl logs -n opensandbox-system -l control-plane=controller-manager -f +``` + +### Check CRD installation + +```bash +kubectl get crd | grep opensandbox +``` + +### Verify RBAC permissions + +```bash +kubectl auth can-i --as=system:serviceaccount:opensandbox-system:opensandbox-controller-controller-manager create pods +``` + +## Additional Resources + +- [OpenSandbox GitHub](https://github.com/alibaba/OpenSandbox) +- [Documentation](https://github.com/alibaba/OpenSandbox/blob/main/kubernetes/README.md) +- [Examples](https://github.com/alibaba/OpenSandbox/tree/main/kubernetes/config/samples) + +## License + +Apache 2.0 License diff --git a/kubernetes/charts/opensandbox-controller/templates/NOTES.txt b/kubernetes/charts/opensandbox-controller/templates/NOTES.txt new file mode 100644 index 00000000..db7b6e7a --- /dev/null +++ b/kubernetes/charts/opensandbox-controller/templates/NOTES.txt @@ -0,0 +1,96 @@ +Thank you for installing {{ .Chart.Name }}! + +Your release is named {{ .Release.Name }}. + +To learn more about the release, try: + + $ helm status {{ .Release.Name }} -n {{ include "opensandbox.namespace" . }} + $ helm get all {{ .Release.Name }} -n {{ include "opensandbox.namespace" . }} + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +🎉 OpenSandbox Controller has been successfully installed! + +📋 Verify the installation: + + kubectl --namespace {{ include "opensandbox.namespace" . }} get pods -l "app.kubernetes.io/name={{ include "opensandbox.name" . }}" + +📚 Check the installed CRDs: + + kubectl get crd batchsandboxes.sandbox.opensandbox.io + kubectl get crd pools.sandbox.opensandbox.io + +🚀 Create your first resources: + + # Create a resource pool + cat </controller \ + --set controller.image.tag=v0.0.1 \ + --namespace opensandbox-system \ + --create-namespace +``` + +### 方式二: 本地 Chart 安装 + +如果您从源码构建,可以使用本地 Chart: + +#### 1. 构建镜像 + +首先构建 controller 和 task-executor 镜像: + +```bash +# 构建 controller 镜像 +cd kubernetes +COMPONENT=controller TAG=v0.0.1 ./build.sh + +# 构建 task-executor 镜像 +COMPONENT=task-executor TAG=v0.0.1 ./build.sh +``` + +#### 2. 安装本地 Helm Chart + +```bash +helm install opensandbox ./charts/opensandbox-controller \ + --set controller.image.repository=/controller \ + --set controller.image.tag=v0.0.1 \ + --namespace opensandbox-system \ + --create-namespace +``` + +或者使用 Makefile: + +```bash +make helm-install \ + IMAGE_TAG_BASE=/controller \ + VERSION=v0.0.1 +``` + +### 3. 验证安装 + +```bash +# 检查 Pod 状态 +kubectl get pods -n opensandbox-system + +# 检查 CRD +kubectl get crd | grep opensandbox + +# 查看安装状态 +helm status opensandbox-controller -n opensandbox-system + +# 查看已安装的 Chart 版本 +helm list -n opensandbox-system +``` + +## 版本管理 + +### 查看可用版本 + +访问 GitHub Releases 查看所有可用版本: +https://github.com/alibaba/OpenSandbox/releases + +查找以 `helm/opensandbox-controller/` 开头的 tag,如 `helm/opensandbox-controller/0.1.0` + +### 升级到指定版本 + +```bash +# 直接从 GitHub Release 升级 +helm upgrade opensandbox-controller \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.2.0/opensandbox-controller-0.2.0.tgz \ + --namespace opensandbox-system +``` + +## 自定义配置 + +### 使用自定义 values 文件 + +创建自定义 values 文件 `custom-values.yaml`: + +```yaml +controller: + image: + repository: myregistry.example.com/opensandbox-controller + tag: v0.1.0 + + resources: + limits: + cpu: 1000m + memory: 512Mi + requests: + cpu: 100m + memory: 128Mi + + logLevel: 5 + +imagePullSecrets: + - name: myregistrykey +``` + +使用自定义配置安装: + +```bash +helm install opensandbox ./charts/opensandbox-controller \ + -f custom-values.yaml \ + --namespace opensandbox-system \ + --create-namespace +``` + +### 常用配置示例 + +#### 1. 调整资源配置 + +```bash +helm install opensandbox ./charts/opensandbox-controller \ + --set controller.resources.limits.cpu=1000m \ + --set controller.resources.limits.memory=512Mi \ + --namespace opensandbox-system +``` + +#### 3. 配置节点亲和性 + +创建 `affinity-values.yaml`: + +```yaml +controller: + resources: + limits: + cpu: 1000m + memory: 512Mi + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: node-role.kubernetes.io/control-plane + operator: Exists +``` + +```bash +helm install opensandbox ./charts/opensandbox-controller \ + -f affinity-values.yaml \ + --namespace opensandbox-system +``` + +## 升级 + +### 升级 Helm Release + +从 GitHub Release 升级: + +```bash +# 升级到指定版本 +helm upgrade opensandbox-controller \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.2.0/opensandbox-controller-0.2.0.tgz \ + --namespace opensandbox-system +``` + +从本地 Chart 升级: + +```bash +helm upgrade opensandbox-controller ./charts/opensandbox-controller \ + --set controller.image.tag=v0.0.2 \ + --namespace opensandbox-system +``` + +或使用 Makefile: + +```bash +make helm-upgrade VERSION=v0.0.2 +``` + +### 查看升级历史 + +```bash +helm history opensandbox-controller -n opensandbox-system +``` + +### 回滚 + +```bash +# 回滚到上一个版本 +helm rollback opensandbox-controller -n opensandbox-system + +# 回滚到指定版本 +helm rollback opensandbox-controller 1 -n opensandbox-system +``` + +## 卸载 + +### 卸载 Helm Release + +```bash +helm uninstall opensandbox-controller -n opensandbox-system +``` + +或使用 Makefile: + +```bash +make helm-uninstall +``` + +**注意**: 默认情况下,CRD 会被保留。如需删除 CRD: + +```bash +kubectl delete crd batchsandboxes.sandbox.opensandbox.io +kubectl delete crd pools.sandbox.opensandbox.io +``` + +### 清理 Namespace + +如果要完全清理: + +```bash +kubectl delete namespace opensandbox-system +``` + +## Makefile 命令 + +项目提供了一系列 Makefile 命令来简化 Helm 操作: + +```bash +# 检查 Helm Chart 语法 +make helm-lint + +# 生成 Kubernetes 清单(不安装) +make helm-template + +# 生成清单并显示调试信息 +make helm-template-debug + +# 打包 Helm Chart +make helm-package + +# 安装 Helm Chart +make helm-install + +# 升级 Helm Chart +make helm-upgrade + +# 卸载 Helm Chart +make helm-uninstall + +# 测试已安装的 Chart +make helm-test + +# 执行 dry-run 安装 +make helm-dry-run + +# 执行所有 Helm 相关任务 +make helm-all +``` + +## 验证部署 + +### 1. 检查 Controller 状态 + +```bash +kubectl get deployment -n opensandbox-system +kubectl get pods -n opensandbox-system +kubectl logs -n opensandbox-system -l control-plane=controller-manager -f +``` + +### 2. 验证 CRD + +```bash +kubectl get crd batchsandboxes.sandbox.opensandbox.io -o yaml +kubectl get crd pools.sandbox.opensandbox.io -o yaml +``` + +### 3. 创建测试资源 + +```bash +# 创建 Pool +kubectl apply -f config/samples/sandbox_v1alpha1_pool.yaml + +# 创建 BatchSandbox +kubectl apply -f config/samples/sandbox_v1alpha1_batchsandbox.yaml + +# 查看状态 +kubectl get pools -n opensandbox-system +kubectl get batchsandboxes -n opensandbox-system +``` + +## 故障排查 + +### Chart 验证失败 + +```bash +# 检查 Chart 语法 +make helm-lint + +# 查看详细模板输出 +make helm-template-debug +``` + +### Controller 无法启动 + +```bash +# 查看 Pod 状态 +kubectl describe pod -n opensandbox-system -l control-plane=controller-manager + +# 查看日志 +kubectl logs -n opensandbox-system -l control-plane=controller-manager + +# 检查 RBAC 权限 +kubectl auth can-i --as=system:serviceaccount:opensandbox-system:opensandbox-opensandbox-controller-controller-manager create pods +``` + +### 镜像拉取失败 + +```bash +# 检查镜像配置 +helm get values opensandbox -n opensandbox-system + +# 添加镜像拉取密钥 +kubectl create secret docker-registry myregistrykey \ + --docker-server= \ + --docker-username= \ + --docker-password= \ + -n opensandbox-system + +# 使用密钥重新安装 +helm upgrade opensandbox ./charts/opensandbox-controller \ + --set imagePullSecrets[0].name=myregistrykey \ + --namespace opensandbox-system +``` + +## 高级配置 + +### 多环境部署 + +为不同环境创建专用的 values 文件: + +#### values-dev.yaml +```yaml +controller: + logLevel: 5 + resources: + limits: + cpu: 200m + memory: 128Mi +``` + +#### values-prod.yaml +```yaml +controller: + logLevel: 2 + replicaCount: 3 + resources: + limits: + cpu: 1000m + memory: 512Mi + affinity: + podAntiAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchExpressions: + - key: control-plane + operator: In + values: + - controller-manager + topologyKey: kubernetes.io/hostname +``` + +部署到不同环境: + +```bash +# 开发环境 +helm install opensandbox ./charts/opensandbox-controller \ + -f values-dev.yaml \ + --namespace opensandbox-dev + +# 生产环境 +helm install opensandbox ./charts/opensandbox-controller \ + -f values-prod.yaml \ + --namespace opensandbox-prod +``` + +## 发布 Helm Chart (维护者使用) + +### 自动发布 + +通过 GitHub Actions 自动发布 Helm Chart: + +#### 方式一: 通过 Git Tag 触发 + +```bash +# 发布 opensandbox-controller chart 版本 0.1.0 +git tag helm/opensandbox-controller/0.1.0 +git push origin helm/opensandbox-controller/0.1.0 +``` + +Tag 命名规则: `helm/{component}/{version}` +- `helm`: 前缀,表示这是 Helm Chart 发布 +- `{component}`: 组件名称,如 `opensandbox-controller` +- `{version}`: 版本号,如 `0.1.0` + +这将自动触发 workflow: +1. 解析 tag 获取 component 和 version +2. 更新对应 Chart.yaml 中的版本号 +3. 打包 Helm Chart +4. 创建 GitHub Release +5. 发布 .tgz 包到 Release + +#### 方式二: 手动触发 + +1. 访问 GitHub Actions 页面 +2. 选择 "Publish Helm Chart" workflow +3. 点击 "Run workflow" +4. 选择 component (如: opensandbox-controller) +5. 输入 chart_version (如: 0.1.0) 和 app_version (如: 0.0.1) +6. 点击运行 + +### 发布后的 URL 格式 + +发布后,用户可以通过以下 URL 访问 Helm Chart: + +``` +https://github.com/alibaba/OpenSandbox/releases/download/helm/{COMPONENT}/{VERSION}/{COMPONENT}-{VERSION}.tgz +``` + +例如: +``` +https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.1.0/opensandbox-controller-0.1.0.tgz +``` + +### 添加新的 Helm Chart 组件 + +如果需要为新组件添加 Helm Chart 发布支持: + +1. 在 `charts/` 目录下创建新组件的 chart 目录 +2. 更新 `.github/workflows/publish-helm-chart.yml`: + - 在 `workflow_dispatch.inputs.component.options` 中添加新组件 + - 在 "Set chart path" step 中添加组件路径映射 + +示例: +```yaml +# 在 workflow_dispatch inputs 中添加 +options: + - opensandbox-controller + - new-component # 新增 + +# 在 Set chart path step 中添加 +if [ "$COMPONENT" == "opensandbox-controller" ]; then + CHART_PATH="kubernetes/charts/opensandbox-controller" +elif [ "$COMPONENT" == "new-component" ]; then + CHART_PATH="path/to/new-component/chart" +fi +``` + +### 本地测试发布流程 + +在发布前,建议本地测试: + +```bash +# 打包 Chart +make helm-package + +# 验证打包的 Chart +helm lint opensandbox-controller-*.tgz + +# 测试安装 +helm install test-release opensandbox-controller-*.tgz \ + --namespace test \ + --create-namespace \ + --dry-run +``` + +## 参考资料 + +- [Helm Chart README](charts/opensandbox-controller/README.md) - 完整的参数列表 +- [OpenSandbox 文档](README.md) - 项目主文档 +- [配置示例](config/samples/) - 资源配置示例 From d9d1b01b948860233b28f129a32555cdd9059f21 Mon Sep 17 00:00:00 2001 From: "pingshan.wj" Date: Thu, 12 Feb 2026 11:27:04 +0800 Subject: [PATCH 3/3] build(k8s): update system namspace from sandbox-k8s-system to opensandbox-system --- .github/workflows/publish-components.yml | 1 + .github/workflows/publish-helm-chart.yml | 19 ++- kubernetes/Makefile | 2 +- kubernetes/README-ZH.md | 134 ++++++++++++++++++ kubernetes/README.md | 134 ++++++++++++++++++ .../templates/_helpers.tpl | 10 +- .../templates/deployment.yaml | 2 +- kubernetes/config/default/kustomization.yaml | 4 +- .../config/default/metrics_service.yaml | 4 +- kubernetes/config/manager/kustomization.yaml | 5 +- kubernetes/config/manager/manager.yaml | 8 +- .../network-policy/allow-metrics-traffic.yaml | 4 +- kubernetes/config/prometheus/monitor.yaml | 4 +- .../config/rbac/batchsandbox_admin_role.yaml | 2 +- .../config/rbac/batchsandbox_editor_role.yaml | 2 +- .../config/rbac/batchsandbox_viewer_role.yaml | 2 +- .../config/rbac/leader_election_role.yaml | 2 +- .../rbac/leader_election_role_binding.yaml | 2 +- kubernetes/config/rbac/pool_admin_role.yaml | 2 +- kubernetes/config/rbac/pool_editor_role.yaml | 2 +- kubernetes/config/rbac/pool_viewer_role.yaml | 2 +- kubernetes/config/rbac/role_binding.yaml | 2 +- kubernetes/config/rbac/service_account.yaml | 2 +- ...ndbox_v1alpha1_batchsandbox-with-task.yaml | 2 +- .../sandbox_v1alpha1_batchsandbox.yaml | 2 +- .../config/samples/sandbox_v1alpha1_pool.yaml | 2 +- .../sandbox_v1alpha1_pooled_batchsandbox.yaml | 2 +- kubernetes/test/e2e/e2e_test.go | 2 +- 28 files changed, 324 insertions(+), 37 deletions(-) diff --git a/.github/workflows/publish-components.yml b/.github/workflows/publish-components.yml index 570714c7..6b281ef6 100644 --- a/.github/workflows/publish-components.yml +++ b/.github/workflows/publish-components.yml @@ -110,5 +110,6 @@ jobs: fi export TAG=$IMAGE_TAG + export COMPONENT=$COMPONENT chmod +x build.sh ./build.sh diff --git a/.github/workflows/publish-helm-chart.yml b/.github/workflows/publish-helm-chart.yml index 27a0ddfa..95a521b2 100644 --- a/.github/workflows/publish-helm-chart.yml +++ b/.github/workflows/publish-helm-chart.yml @@ -110,10 +110,25 @@ jobs: ### Installation - 直接从 Release 安装: + 直接从 GitHub Release 安装: ```bash - helm install ${{ steps.parse_tag.outputs.component }} https://github.com/${{ github.repository }}/releases/download/helm/${{ steps.parse_tag.outputs.component }}/${{ steps.parse_tag.outputs.chart_version }}/${{ steps.parse_tag.outputs.component }}-${{ steps.parse_tag.outputs.chart_version }}.tgz --namespace opensandbox-system --create-namespace + helm install opensandbox \ + https://github.com/${{ github.repository }}/releases/download/helm/${{ steps.parse_tag.outputs.component }}/${{ steps.parse_tag.outputs.chart_version }}/${{ steps.parse_tag.outputs.component }}-${{ steps.parse_tag.outputs.chart_version }}.tgz \ + --namespace opensandbox-system \ + --create-namespace + ``` + + 或者先下载后安装: + + ```bash + # 下载 + wget https://github.com/${{ github.repository }}/releases/download/helm/${{ steps.parse_tag.outputs.component }}/${{ steps.parse_tag.outputs.chart_version }}/${{ steps.parse_tag.outputs.component }}-${{ steps.parse_tag.outputs.chart_version }}.tgz + + # 安装 + helm install opensandbox ./${{ steps.parse_tag.outputs.component }}-${{ steps.parse_tag.outputs.chart_version }}.tgz \ + --namespace opensandbox-system \ + --create-namespace ``` ### What's Changed diff --git a/kubernetes/Makefile b/kubernetes/Makefile index c94c6224..e23d2bf6 100644 --- a/kubernetes/Makefile +++ b/kubernetes/Makefile @@ -29,7 +29,7 @@ BUNDLE_METADATA_OPTS ?= $(BUNDLE_CHANNELS) $(BUNDLE_DEFAULT_CHANNEL) # # For example, running 'make bundle-build bundle-push catalog-build catalog-push' will build and push both # opensandbox.io/sandbox-k8s-bundle:$VERSION and opensandbox.io/sandbox-k8s-catalog:$VERSION. -IMAGE_TAG_BASE ?= opensandbox.io/sandbox-k8s +IMAGE_TAG_BASE ?= sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/controller # BUNDLE_IMG defines the image:tag used for the bundle. # You can use it as an arg. (E.g make bundle-build BUNDLE_IMG=/:) diff --git a/kubernetes/README-ZH.md b/kubernetes/README-ZH.md index 5ad5cf80..cb8fedd0 100644 --- a/kubernetes/README-ZH.md +++ b/kubernetes/README-ZH.md @@ -148,6 +148,140 @@ kind delete cluster 此项目需要两个独立的镜像 - 一个用于控制器，另一个用于任务执行器组件。 +#### 方式 1：使用 Helm 部署（推荐） + +**从 GitHub Release 安装：** + +您可以直接从 GitHub Releases 安装 OpenSandbox Controller。查看 [Releases 页面](https://github.com/alibaba/OpenSandbox/releases?q=helm%2Fopensandbox-controller&expanded=true) 了解所有可用版本。 + +```sh +# 将 替换为所需版本（例如：0.1.0） +helm install opensandbox \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller//opensandbox-controller-.tgz \ + --namespace opensandbox-system \ + --create-namespace +``` + +具体版本示例： +```sh +helm install opensandbox \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.1.0/opensandbox-controller-0.1.0.tgz \ + --namespace opensandbox-system \ + --create-namespace +``` + +您也可以先下载 chart 然后再安装： +```sh +# 下载 chart +wget https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller//opensandbox-controller-.tgz + +# 从本地文件安装 +helm install opensandbox ./opensandbox-controller-.tgz \ + --namespace opensandbox-system \ + --create-namespace +``` + +**自定义安装：** + +使用 `--set` 参数自定义配置： + +```sh +# 示例：自定义资源限制 +helm install opensandbox \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.1.0/opensandbox-controller-0.1.0.tgz \ + --namespace opensandbox-system \ + --create-namespace \ + --set controller.replicaCount=2 \ + --set controller.resources.limits.cpu=1000m \ + --set controller.resources.limits.memory=512Mi + +# 示例：自定义日志级别和并发数 +helm install opensandbox \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.1.0/opensandbox-controller-0.1.0.tgz \ + --namespace opensandbox-system \ + --create-namespace \ + --set controller.logLevel=5 \ + --set controller.batchSandboxConcurrency=64 +``` + +或使用 values 文件进行复杂配置： + +```sh +# 创建自定义 values 文件 +cat > custom-values.yaml </opensandbox-controller:tag + + # 构建和推送任务执行器镜像 + make docker-build-task-executor docker-push-task-executor TASK_EXECUTOR_IMG=/opensandbox-task-executor:tag + ``` + +2. **使用 Helm 安装：** + ```sh + helm install opensandbox ./charts/opensandbox-controller \ + --set controller.image.repository=/opensandbox-controller \ + --set controller.image.tag= \ + --namespace opensandbox-system \ + --create-namespace + ``` + +**验证安装：** + +检查控制器是否运行： +```sh +kubectl get pods -n opensandbox-system +kubectl get deployment -n opensandbox-system + +# 查看日志 +kubectl logs -n opensandbox-system -l control-plane=controller-manager -f +``` + +**升级：** + +```sh +# 升级到新版本 +helm upgrade opensandbox \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller//opensandbox-controller-.tgz \ + --namespace opensandbox-system +``` + +**卸载：** + +```sh +helm uninstall opensandbox -n opensandbox-system +``` + +有关更多配置选项和高级用法，请参阅 [Helm Chart README](charts/opensandbox-controller/README.md)。 + +#### 方式 2：使用 Kustomize 部署 + 1. **构建和推送您的镜像：** ```sh # 构建和推送控制器镜像 diff --git a/kubernetes/README.md b/kubernetes/README.md index 98e06bd2..d48377ba 100644 --- a/kubernetes/README.md +++ b/kubernetes/README.md @@ -147,6 +147,140 @@ For more detailed instructions on using kind, please refer to the [official kind This project requires two separate images - one for the controller and another for the task-executor component. +#### Option 1: Deploy with Helm (Recommended) + +**Install from GitHub Release:** + +You can install OpenSandbox Controller directly from GitHub Releases. Check the [Releases page](https://github.com/alibaba/OpenSandbox/releases?q=helm%2Fopensandbox-controller&expanded=true) for all available versions. + +```sh +# Replace with the desired version (e.g., 0.1.0) +helm install opensandbox \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller//opensandbox-controller-.tgz \ + --namespace opensandbox-system \ + --create-namespace +``` + +Example with specific version: +```sh +helm install opensandbox \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.1.0/opensandbox-controller-0.1.0.tgz \ + --namespace opensandbox-system \ + --create-namespace +``` + +You can also download the chart first and then install: +```sh +# Download the chart +wget https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller//opensandbox-controller-.tgz + +# Install from local file +helm install opensandbox ./opensandbox-controller-.tgz \ + --namespace opensandbox-system \ + --create-namespace +``` + +**Customize Installation:** + +Use `--set` flags to customize the configuration: + +```sh +# Example: Custom resource limits +helm install opensandbox \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.1.0/opensandbox-controller-0.1.0.tgz \ + --namespace opensandbox-system \ + --create-namespace \ + --set controller.replicaCount=2 \ + --set controller.resources.limits.cpu=1000m \ + --set controller.resources.limits.memory=512Mi + +# Example: Custom log level and concurrency +helm install opensandbox \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.1.0/opensandbox-controller-0.1.0.tgz \ + --namespace opensandbox-system \ + --create-namespace \ + --set controller.logLevel=5 \ + --set controller.batchSandboxConcurrency=64 +``` + +Or use a values file for complex configurations: + +```sh +# Create a custom values file +cat > custom-values.yaml </opensandbox-controller:tag + + # Build and push the task-executor image + make docker-build-task-executor docker-push-task-executor TASK_EXECUTOR_IMG=/opensandbox-task-executor:tag + ``` + +2. **Install with Helm:** + ```sh + helm install opensandbox ./charts/opensandbox-controller \ + --set controller.image.repository=/opensandbox-controller \ + --set controller.image.tag= \ + --namespace opensandbox-system \ + --create-namespace + ``` + +**Verify Installation:** + +Check the controller is running: +```sh +kubectl get pods -n opensandbox-system +kubectl get deployment -n opensandbox-system + +# Check logs +kubectl logs -n opensandbox-system -l control-plane=controller-manager -f +``` + +**Upgrade:** + +```sh +# Upgrade to a new version +helm upgrade opensandbox \ + https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller//opensandbox-controller-.tgz \ + --namespace opensandbox-system +``` + +**Uninstall:** + +```sh +helm uninstall opensandbox -n opensandbox-system +``` + +For more configuration options and advanced usage, see the [Helm Chart README](charts/opensandbox-controller/README.md). + +#### Option 2: Deploy with Kustomize + 1. **Build and push your images:** ```sh # Build and push the controller image diff --git a/kubernetes/charts/opensandbox-controller/templates/_helpers.tpl b/kubernetes/charts/opensandbox-controller/templates/_helpers.tpl index f88c2170..b6b9d3b7 100644 --- a/kubernetes/charts/opensandbox-controller/templates/_helpers.tpl +++ b/kubernetes/charts/opensandbox-controller/templates/_helpers.tpl @@ -2,7 +2,7 @@ Expand the name of the chart. */}} {{- define "opensandbox.name" -}} -{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }} +{{- default "opensandbox" .Values.nameOverride | trunc 63 | trimSuffix "-" }} {{- end }} {{/* @@ -56,7 +56,7 @@ Create the name of the service account to use */}} {{- define "opensandbox.serviceAccountName" -}} {{- if .Values.serviceAccount.create }} -{{- default (printf "%s-controller-manager" (include "opensandbox.fullname" .)) .Values.serviceAccount.name }} +{{- default "opensandbox-controller-manager" .Values.serviceAccount.name }} {{- else }} {{- default "default" .Values.serviceAccount.name }} {{- end }} @@ -69,7 +69,7 @@ Get the namespace to use {{- if .Values.namespaceOverride }} {{- .Values.namespaceOverride }} {{- else }} -{{- printf "%s-system" (include "opensandbox.name" .) }} +{{- print "opensandbox-system" }} {{- end }} {{- end }} @@ -85,14 +85,14 @@ Controller image Create the name for the leader election role */}} {{- define "opensandbox.leaderElectionRoleName" -}} -{{- printf "%s-leader-election-role" (include "opensandbox.fullname" .) | trunc 63 | trimSuffix "-" }} +{{- print "opensandbox-leader-election-role" }} {{- end }} {{/* Create the name for the manager role */}} {{- define "opensandbox.managerRoleName" -}} -{{- printf "%s-manager-role" (include "opensandbox.fullname" .) | trunc 63 | trimSuffix "-" }} +{{- print "opensandbox-manager-role" }} {{- end }} {{/* diff --git a/kubernetes/charts/opensandbox-controller/templates/deployment.yaml b/kubernetes/charts/opensandbox-controller/templates/deployment.yaml index 13556019..fb0e5f35 100644 --- a/kubernetes/charts/opensandbox-controller/templates/deployment.yaml +++ b/kubernetes/charts/opensandbox-controller/templates/deployment.yaml @@ -1,7 +1,7 @@ apiVersion: apps/v1 kind: Deployment metadata: - name: {{ include "opensandbox.fullname" . }}-controller-manager + name: opensandbox-controller-manager namespace: {{ include "opensandbox.namespace" . }} labels: {{- include "opensandbox.labels" . | nindent 4 }} diff --git a/kubernetes/config/default/kustomization.yaml b/kubernetes/config/default/kustomization.yaml index eb84d905..df90f6f1 100644 --- a/kubernetes/config/default/kustomization.yaml +++ b/kubernetes/config/default/kustomization.yaml @@ -1,12 +1,12 @@ # Adds namespace to all resources. -namespace: sandbox-k8s-system +namespace: opensandbox-system # Value of this field is prepended to the # names of all resources, e.g. a deployment named # "wordpress" becomes "alices-wordpress". # Note that it should also match with the prefix (text before '-') of the namespace # field above. -namePrefix: sandbox-k8s- +namePrefix: opensandbox- # Labels to add to all resources and selectors. #labels: diff --git a/kubernetes/config/default/metrics_service.yaml b/kubernetes/config/default/metrics_service.yaml index c65f4324..0c4361be 100644 --- a/kubernetes/config/default/metrics_service.yaml +++ b/kubernetes/config/default/metrics_service.yaml @@ -3,7 +3,7 @@ kind: Service metadata: labels: control-plane: controller-manager - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: controller-manager-metrics-service namespace: system @@ -15,4 +15,4 @@ spec: targetPort: 8443 selector: control-plane: controller-manager - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox diff --git a/kubernetes/config/manager/kustomization.yaml b/kubernetes/config/manager/kustomization.yaml index 3b71d99d..ae9eb8f4 100644 --- a/kubernetes/config/manager/kustomization.yaml +++ b/kubernetes/config/manager/kustomization.yaml @@ -4,5 +4,8 @@ apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization images: - name: controller - newName: example.com/sandbox-k8s + newName: controller + newTag: dev +- name: manager + newName: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/controller newTag: v0.0.1 diff --git a/kubernetes/config/manager/manager.yaml b/kubernetes/config/manager/manager.yaml index 5ac3d9d3..bda87180 100644 --- a/kubernetes/config/manager/manager.yaml +++ b/kubernetes/config/manager/manager.yaml @@ -3,7 +3,7 @@ kind: Namespace metadata: labels: control-plane: controller-manager - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: system --- @@ -14,13 +14,13 @@ metadata: namespace: system labels: control-plane: controller-manager - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize spec: selector: matchLabels: control-plane: controller-manager - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox replicas: 1 template: metadata: @@ -28,7 +28,7 @@ spec: kubectl.kubernetes.io/default-container: manager labels: control-plane: controller-manager - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox spec: # TODO(user): Uncomment the following code to configure the nodeAffinity expression # according to the platforms which are supported by your solution. diff --git a/kubernetes/config/network-policy/allow-metrics-traffic.yaml b/kubernetes/config/network-policy/allow-metrics-traffic.yaml index 150fc5d9..d5020880 100644 --- a/kubernetes/config/network-policy/allow-metrics-traffic.yaml +++ b/kubernetes/config/network-policy/allow-metrics-traffic.yaml @@ -5,7 +5,7 @@ apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: allow-metrics-traffic namespace: system @@ -13,7 +13,7 @@ spec: podSelector: matchLabels: control-plane: controller-manager - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox policyTypes: - Ingress ingress: diff --git a/kubernetes/config/prometheus/monitor.yaml b/kubernetes/config/prometheus/monitor.yaml index 6e6ee304..4a0e7904 100644 --- a/kubernetes/config/prometheus/monitor.yaml +++ b/kubernetes/config/prometheus/monitor.yaml @@ -4,7 +4,7 @@ kind: ServiceMonitor metadata: labels: control-plane: controller-manager - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: controller-manager-metrics-monitor namespace: system @@ -24,4 +24,4 @@ spec: selector: matchLabels: control-plane: controller-manager - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox diff --git a/kubernetes/config/rbac/batchsandbox_admin_role.yaml b/kubernetes/config/rbac/batchsandbox_admin_role.yaml index d7ea994d..7e8942d7 100644 --- a/kubernetes/config/rbac/batchsandbox_admin_role.yaml +++ b/kubernetes/config/rbac/batchsandbox_admin_role.yaml @@ -9,7 +9,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: batchsandbox-admin-role rules: diff --git a/kubernetes/config/rbac/batchsandbox_editor_role.yaml b/kubernetes/config/rbac/batchsandbox_editor_role.yaml index 40e7ef7f..19f27753 100644 --- a/kubernetes/config/rbac/batchsandbox_editor_role.yaml +++ b/kubernetes/config/rbac/batchsandbox_editor_role.yaml @@ -9,7 +9,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: batchsandbox-editor-role rules: diff --git a/kubernetes/config/rbac/batchsandbox_viewer_role.yaml b/kubernetes/config/rbac/batchsandbox_viewer_role.yaml index 24460902..0ce89c2c 100644 --- a/kubernetes/config/rbac/batchsandbox_viewer_role.yaml +++ b/kubernetes/config/rbac/batchsandbox_viewer_role.yaml @@ -9,7 +9,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: batchsandbox-viewer-role rules: diff --git a/kubernetes/config/rbac/leader_election_role.yaml b/kubernetes/config/rbac/leader_election_role.yaml index 01d15198..368297c7 100644 --- a/kubernetes/config/rbac/leader_election_role.yaml +++ b/kubernetes/config/rbac/leader_election_role.yaml @@ -3,7 +3,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: leader-election-role rules: diff --git a/kubernetes/config/rbac/leader_election_role_binding.yaml b/kubernetes/config/rbac/leader_election_role_binding.yaml index d0c2ad16..61f4fd3b 100644 --- a/kubernetes/config/rbac/leader_election_role_binding.yaml +++ b/kubernetes/config/rbac/leader_election_role_binding.yaml @@ -2,7 +2,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: leader-election-rolebinding roleRef: diff --git a/kubernetes/config/rbac/pool_admin_role.yaml b/kubernetes/config/rbac/pool_admin_role.yaml index e9dd6d01..98662847 100644 --- a/kubernetes/config/rbac/pool_admin_role.yaml +++ b/kubernetes/config/rbac/pool_admin_role.yaml @@ -9,7 +9,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: pool-admin-role rules: diff --git a/kubernetes/config/rbac/pool_editor_role.yaml b/kubernetes/config/rbac/pool_editor_role.yaml index fbba1957..d1f913d9 100644 --- a/kubernetes/config/rbac/pool_editor_role.yaml +++ b/kubernetes/config/rbac/pool_editor_role.yaml @@ -9,7 +9,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: pool-editor-role rules: diff --git a/kubernetes/config/rbac/pool_viewer_role.yaml b/kubernetes/config/rbac/pool_viewer_role.yaml index 477f9a47..764f871b 100644 --- a/kubernetes/config/rbac/pool_viewer_role.yaml +++ b/kubernetes/config/rbac/pool_viewer_role.yaml @@ -9,7 +9,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: pool-viewer-role rules: diff --git a/kubernetes/config/rbac/role_binding.yaml b/kubernetes/config/rbac/role_binding.yaml index 29e9790e..ae21cd5c 100644 --- a/kubernetes/config/rbac/role_binding.yaml +++ b/kubernetes/config/rbac/role_binding.yaml @@ -2,7 +2,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: manager-rolebinding roleRef: diff --git a/kubernetes/config/rbac/service_account.yaml b/kubernetes/config/rbac/service_account.yaml index 9e28dc41..616c5813 100644 --- a/kubernetes/config/rbac/service_account.yaml +++ b/kubernetes/config/rbac/service_account.yaml @@ -2,7 +2,7 @@ apiVersion: v1 kind: ServiceAccount metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: controller-manager namespace: system diff --git a/kubernetes/config/samples/sandbox_v1alpha1_batchsandbox-with-task.yaml b/kubernetes/config/samples/sandbox_v1alpha1_batchsandbox-with-task.yaml index a3e1cb16..41d83985 100644 --- a/kubernetes/config/samples/sandbox_v1alpha1_batchsandbox-with-task.yaml +++ b/kubernetes/config/samples/sandbox_v1alpha1_batchsandbox-with-task.yaml @@ -2,7 +2,7 @@ apiVersion: sandbox.opensandbox.io/v1alpha1 kind: BatchSandbox metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: batchsandbox-sample namespace: opensandbox diff --git a/kubernetes/config/samples/sandbox_v1alpha1_batchsandbox.yaml b/kubernetes/config/samples/sandbox_v1alpha1_batchsandbox.yaml index 8c94fc72..1a64d7fe 100644 --- a/kubernetes/config/samples/sandbox_v1alpha1_batchsandbox.yaml +++ b/kubernetes/config/samples/sandbox_v1alpha1_batchsandbox.yaml @@ -2,7 +2,7 @@ apiVersion: sandbox.opensandbox.io/v1alpha1 kind: BatchSandbox metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: batchsandbox-sample namespace: opensandbox diff --git a/kubernetes/config/samples/sandbox_v1alpha1_pool.yaml b/kubernetes/config/samples/sandbox_v1alpha1_pool.yaml index d27d5d25..911398d0 100644 --- a/kubernetes/config/samples/sandbox_v1alpha1_pool.yaml +++ b/kubernetes/config/samples/sandbox_v1alpha1_pool.yaml @@ -2,7 +2,7 @@ apiVersion: sandbox.opensandbox.io/v1alpha1 kind: Pool metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: pool-sample namespace: opensandbox diff --git a/kubernetes/config/samples/sandbox_v1alpha1_pooled_batchsandbox.yaml b/kubernetes/config/samples/sandbox_v1alpha1_pooled_batchsandbox.yaml index efbb84d1..00a2162a 100644 --- a/kubernetes/config/samples/sandbox_v1alpha1_pooled_batchsandbox.yaml +++ b/kubernetes/config/samples/sandbox_v1alpha1_pooled_batchsandbox.yaml @@ -2,7 +2,7 @@ apiVersion: sandbox.opensandbox.io/v1alpha1 kind: BatchSandbox metadata: labels: - app.kubernetes.io/name: sandbox-k8s + app.kubernetes.io/name: opensandbox app.kubernetes.io/managed-by: kustomize name: batchsandbox-pool-sample namespace: opensandbox diff --git a/kubernetes/test/e2e/e2e_test.go b/kubernetes/test/e2e/e2e_test.go index 98ea07c3..298e5a28 100644 --- a/kubernetes/test/e2e/e2e_test.go +++ b/kubernetes/test/e2e/e2e_test.go @@ -32,7 +32,7 @@ import ( ) // namespace where the project is deployed in -const namespace = "sandbox-k8s-system" +const namespace = "opensandbox-system" var _ = Describe("Manager", Ordered, func() { var controllerPodName string