FastGPT/deploy/helm/opensandbox/scripts/README.md

OpenSandbox Helm Chart Scripts

This directory contains utility scripts for OpenSandbox Controller deployment and testing.

Script List

1. install.sh - Installation Script

Interactive installation of OpenSandbox Controller to Kubernetes cluster.

Features:

• Automatic detection of sudo privilege requirements
• Validation of dependency tools (helm, kubectl)
• Cluster connection verification
• Support for multiple deployment environments:
  • Default configuration (values.yaml)
  • E2E testing (values-e2e.yaml)
  • Custom configuration (via --set or custom values file)
• Helm Chart validation
• Display verification commands after deployment

Usage:

cd scripts
./install.sh

Environment Variables:

• IMAGE_REPO - Override controller image repository
• IMAGE_TAG - Override controller image tag
• SERVER_IMAGE_REPO - Override server image repository
• SERVER_IMAGE_TAG - Override server image tag

Example:

# Using custom images
IMAGE_REPO=myregistry.com/controller \
IMAGE_TAG=v1.0.0 \
SERVER_IMAGE_REPO=myregistry.com/server \
SERVER_IMAGE_TAG=v0.1.0 \
./install.sh

2. uninstall.sh - Uninstallation Script

Uninstall OpenSandbox Controller and clean up related resources.

Features:

• Check running BatchSandbox and Pool resources
• Display Controller and Server deployment status
• Optional CRD deletion
• Optional namespace deletion
• Post-uninstall cleanup verification

Usage:

cd scripts
./uninstall.sh

Environment Variables:

• RELEASE_NAME - Release name (default: opensandbox-controller)
• NAMESPACE - Namespace (default: opensandbox)

Example:

# Uninstall specific release
RELEASE_NAME=my-release NAMESPACE=my-namespace ./uninstall.sh

3. e2e-test.sh - End-to-End Test Script

Execute complete end-to-end test workflow.

Test Workflow:

1. Helm Install (using values-e2e.yaml)
2. Verify Controller and Server deployment
3. Verify Pool deployment
4. Verify SDK calls
5. Helm Uninstall

Features:

• Automatic Server port-forward setup
• Server API health check validation
• Pool Pod execd process verification
• SDK integration test execution
• Automatic resource cleanup (including port-forward processes)

Usage:

cd scripts
./e2e-test.sh [VALUES_FILE]

# Using default values-e2e.yaml
./e2e-test.sh

# Using custom values file
./e2e-test.sh custom-values.yaml

Prerequisites:

• Required Docker images must be loaded:
  • opensandbox/controller:dev
  • opensandbox/server:v0.1.0
  • opensandbox/task-executor:dev
  • opensandbox/execd:v1.0.5
  • nginx:latest
• Python SDK installed (using uv)
• Cluster has sufficient resources to run test Pods

General Instructions

Sudo Privileges

All scripts automatically detect whether sudo privileges are required to execute kubectl and helm commands.

Script Paths

Scripts use relative paths to locate the Chart directory and can be invoked from any location:

# From chart root directory
./scripts/install.sh

# From scripts directory
cd scripts
./install.sh

# From other directory
/path/to/opensandbox-controller/scripts/install.sh

Colored Output

Scripts use ANSI color codes to enhance readability:

• 🟢 Green - Success messages
• 🟡 Yellow - Warnings and step titles
• 🔴 Red - Error messages

Error Handling

All scripts use set -e, exiting immediately on errors. The e2e-test.sh uses trap to ensure cleanup functions execute on exit.

Troubleshooting

install.sh

Issue: Cannot connect to Kubernetes cluster

# Check kubeconfig
kubectl cluster-info

# Check context
kubectl config current-context

Issue: Chart validation fails

# Manual validation
helm lint ../

uninstall.sh

Issue: Resources are still running

# View all BatchSandbox
kubectl get batchsandboxes -A

# View all Pool
kubectl get pools -A

# Delete all resources
kubectl delete batchsandboxes --all -A
kubectl delete pools --all -A

e2e-test.sh

Issue: Port-forward fails

# Check if any process is using port 8080
lsof -i :8080

# Manual port-forward test
kubectl port-forward -n opensandbox svc/opensandbox-controller-server 8080:8080

Issue: SDK test fails

# Check Server logs
kubectl logs -n opensandbox -l app.kubernetes.io/component=server

# Check Pool Pod logs
kubectl logs -n opensandbox -l pool=agent-pool

# Test Server API
curl http://localhost:8080/health

Issue: Image not found

# Check if images are loaded
docker images | grep opensandbox

# Reload images
docker load -i /path/to/image.tar

Development Guide

Modifying Scripts

After modifying scripts, ensure:

1. Maintain consistent error handling
2. Update related documentation
3. Use meaningful colored output
4. Add appropriate validation steps

Adding New Scripts

New scripts should follow these conventions:

• Use #!/bin/bash shebang
• Use set -e to enable exit-on-error
• Implement automatic sudo detection
• Add colored output for readability
• Add documentation in this README

License

Apache License 2.0