Container Compute Service:Create an Agent Sandbox in an ACS cluster

Before you begin

1. Create an ACS cluster and activate Agent Sandbox.

2. If you have an existing cluster, you must upgrade the following components after activating the service.

   1. Upgrade the acs-virtual-node component to v2.17.0 or later.

   2. Upgrade the Kube Scheduler component version.

      Cluster version	Kube Scheduler component version
      v1.28	v1.28.12-aliyun-1.4.6 or later
      v1.30	v1.30.3-aliyun-1.6.2 or later
      v1.31	v1.31.0-aliyun-1.5.2 or later
      v1.32	v1.32.0-apsara.6.11.11.3187ac8f or later

Install components

1. Log on to the ACS console. In the left navigation pane, click Clusters.

2. On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Add-ons.

3. Install the Ingress controller and sandbox-related components.

   1. Install an Ingress controller.

      Install an Ingress controller component supported by ACS to access the sandbox-manager service from outside the cluster. The following steps use Install the ALB Ingress Controller as an example to create a new public-facing ALB instance.

   2. Install the ack-agent-sandbox-controller component.

      When you install this component for the first time, you must grant the AliyunCSManagedAgentSandboxRole role permissions to access your cloud resources. You can use the default parameter settings. If you require higher concurrency, you can increase the resource specifications.

      For more information about the features of this component, see ack-agent-sandbox-controller.

   3. Install the ack-sandbox-manager component.

      1. Prepare an E2B domain name.

         For more information about preparing a domain name, configuring DNS resolution, and applying for a certificate, see Use in a production environment.

      2. Configure the component parameters.

         Change className to alb (the IngressClass that is automatically created when you install the Ingress controller component), change domain to your actual domain name, and change adminApiKey to a custom API Key. Keep the other configurations at their default values. After the component is installed, an Ingress named sandbox-manager is created in the sandbox-system namespace.

         Parameter details

         Parameter	Parameter	Description
         sandboxManager	replicaCount	Number ofsandbox-manager instances. Default: 3.
         E2B	domain	The E2B domain name. For more information, see Prepare a domain name.
         	Enable E2B_API_KEY verification	Specifies whether to enable API_KEY authentication. This feature is enabled by default.
         	adminApiKey	If authentication is enabled, this parameter sets the initial key for the first installation. Replace the default value with your custom API key.
         Controller	logLevel	The log level of the controller. Default: 1.
         	resources.requests.cpu	The CPU resource request for the controller. Default: 2.
         	resources.requests.memory	The memory resource request for the controller. Default: 4 Gi.
         Proxy	resources.requests.cpu	The CPU resource request for the proxy. Default: 2.
         	resources.requests.memory	The memory resource request for the proxy. Default: 4 Gi.
         Ingress	className	The IngressClass name configured in the cluster, such as alb, mse.

      3. If you use the ALB Ingress controller, you must also add an HTTPS:443 listener for both the ALB instance and the Ingress.

         Update the AlbConfig to add anHTTPS:443 listener for the ALB instance.

         1. In the navigation pane on the left, choose Workloads > Custom Resources. On the Resource Objects tab, search for and click AlbConfig.

         2. In the list of AlbConfig resource objects, find the target resource alb, and click Edit YAML in the Actions column to its right.

         3. Add the spec.listeners.port: 443 and spec.listeners.protocol: HTTPS fields, then click OK.

            spec:
              config:
                addressAllocatedMode: Fixed
                addressType: Internet
                zoneMappings:
                  - vSwitchId: vsw-xxx
                  - vSwitchId: vsw-xxx
              listeners:
                - port: 80
                  protocol: HTTP
                - port: 443
                  protocol: HTTPS

         Update the Ingress to associate the HTTPS:443 listener.

         1. In the left navigation bar, select Network > Ingresses. In the Actions column for the sandbox-manager ingress, click Update.

         2. Add the following configuration, and click OK.

            • Annotations: alb.ingress.kubernetes.io/listen-ports: [{"HTTP": 80}, {"HTTPS": 443}]

Create an Agent Sandbox

Replace the Agent Sandbox container image

from e2b_code_interpreter import Sandbox
# The default timeout period is 300 seconds.
sbx = Sandbox.create(template="some-template", timeout=300, metadata={
    # Perform an in-place update to replace the sandbox container's image with the specified image.
    "e2b.agents.kruise.io/image": "<YOUR_IMAGE>"
})

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxClaim
metadata:
  name: my-sandbox-claim
  namespace: default
spec:
  templateName: code-interpreter    # The name of the SandboxSet warm pool.
  replicas: 1
  claimTimeout: 5m
  ttlAfterCompleted: 15m
  inplaceUpdate:
    # The target image for the update.
    image: <YOUR_IMAGE> # Replace cn-zhangjiakou with your actual region ID. 

Agent Sandbox resource specifications

When you allocate a sandbox from a warm pool, in-place vertical scaling (VPA) is supported. This allows you to scale up low-specification sandbox instances to meet your business requirements without re-creating Pods. This approach combines the rapid provisioning of a warm pool with the flexibility to meet diverse resource demands.

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxSet
metadata:
  name: code-interpreter
spec:
  template:
    metadata:
      annotations:
        # Allows in-place VPA when a sandbox is allocated from the warm pool.
        scaling.alibabacloud.com/enable-inplace-resource-resize: "true"
    spec:
      containers:
        - name: interpreter
          image: xxx
          resources:
            requests:
              cpu: 500m     
              memory: 1Gi 
            limits:
              cpu: 500m 
              memory: 1Gi
  replicas: 5  # The number of warm instances.

from e2b_code_interpreter import Sandbox
sbx = Sandbox.create(template="code-interpreter", metadata={
    "e2b.agents.kruise.io/cpu-request": "1000m",
    "e2b.agents.kruise.io/cpu-limit": "1000m"
})

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxClaim
metadata:
  name: code-interpreter-vpa-claim
  namespace: default
spec:
  templateName: code-interpreter
  replicas: 1
  claimTimeout: 5m
  ttlAfterCompleted: 15m
  inplaceUpdate:  # Declare the target resource specifications.
    resources:
      requests:
        cpu: 1000m
      limits:
        cpu: 1000m

Delete an Agent Sandbox

To permanently remove an instance, delete the sandbox by using one of the following methods.

from e2b_code_interpreter import Sandbox
sandbox = Sandbox.connect("<YOUR_SANDBOX_ID>")
sandbox.kill()

# Before you run the command, replace <NAMESPACE> with the Namespace of the resource and <RESOURCE_NAME> with the name of the CR.
kubectl -n <NAMESPACE> delete sandbox <RESOURCE_NAME>

Production environment

kubectl create secret tls sandbox-manager-tls \
        --cert=fullchain.pem \
        --key=privkey.pem -n sandbox-system

export SSL_CERT_FILE=/path/to/ca-fullchain.pem
python main.py # Call the E2B SDK by using Python.

sudo certbot certonly \
  --manual \
  --preferred-challenges=dns \
  --email your-email@example.com \
  --server https://acme-v02.api.letsencrypt.org/directory \
  --agree-tos \
  -d "your.domain.com" \
  -d "*.your.domain.com"

sudo cp /etc/letsencrypt/live/your.domain.com/fullchain.pem ./fullchain.pem
sudo cp /etc/letsencrypt/live/your.domain.com/privkey.pem ./privkey.pem

kubectl create secret tls sandbox-manager-tls \
  --cert=fullchain.pem \
  --key=privkey.pem \
  --namespace=sandbox-system

kubectl get ingress sandbox-manager -o jsonpath='{range .status.loadBalancer.ingress[*]}{.hostname}{.ip}{"\n"}{end}' -n sandbox-system

FAQ