Template pre-warming

Step 1: Initialize the SDK client

Install the Go software development kit (SDK) and its dependencies.

go get github.com/alibabacloud-go/sandbox-20260820/client
go get github.com/alibabacloud-go/darabonba-openapi/v2/utils
go get github.com/alibabacloud-go/tea/dara

Set the access credentials:

export ALIBABA_CLOUD_ACCESS_KEY_ID="<YOUR-ACCESS-KEY-ID>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<YOUR-ACCESS-KEY-SECRET>"
# If you use STS temporary credentials, also set the following variable:
# export ALIBABA_CLOUD_SECURITY_TOKEN="<YOUR-SECURITY-TOKEN>"

The following examples are based on OpenAPI version 2026-08-20. Subsequent steps reuse this client initialization code, so the import statements are not listed again.

package main

import (
    "fmt"
    "os"
    "time"

    openapiutil "github.com/alibabacloud-go/darabonba-openapi/v2/utils"
    sandbox "github.com/alibabacloud-go/sandbox-20260820/client"
    "github.com/alibabacloud-go/tea/dara"
)

func newClient(region string) (*sandbox.Client, error) {
    return sandbox.NewClient(&openapiutil.Config{
        AccessKeyId:     dara.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")),
        AccessKeySecret: dara.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")),
        SecurityToken:   dara.String(os.Getenv("ALIBABA_CLOUD_SECURITY_TOKEN")),
        Endpoint:        dara.String("sandbox." + region + ".aliyuncs.com"),
        Protocol:        dara.String("https"),
    })
}

A long-term AccessKey does not require ALIBABA_CLOUD_SECURITY_TOKEN. Set ALIBABA_CLOUD_SECURITY_TOKEN when you use STS temporary credentials.

Step 2: Create a pre-warming task and poll until the task is ready

Call CreateTemplateCache to submit the pre-warming task, and then call DescribeTemplateCache to poll the task until status changes to ready. A successful request indicates that the platform has accepted the task, and the pre-warming runs asynchronously in the background. Acceptance does not indicate that the pre-warming is complete. The example polls every 15 seconds and waits for at most 20 minutes. If the wait times out, continue to query the task status instead of creating the task again. If the build status (status.state ) of the template is not ready, CreateTemplateCache returns 409 TemplateNotReady, and no pre-warming task is created.

func createAndWait(client *sandbox.Client, teamID, templateID string) error {
    resp, err := client.CreateTemplateCache(&sandbox.CreateTemplateCacheRequest{
        Body: &sandbox.CreateTemplateCacheInput{
            TeamID:     dara.String(teamID),
            TemplateID: dara.String(templateID),
        },
    })
    if err != nil {
        return fmt.Errorf("CreateTemplateCache: %w", err)
    }

    cache := resp.Body.TemplateCache
    fmt.Printf("accepted: status=%s requestId=%s\n",
        dara.StringValue(cache.Status), dara.StringValue(resp.Body.RequestId))

    deadline := time.Now().Add(20 * time.Minute)
    for time.Now().Before(deadline) {
        got, err := client.DescribeTemplateCache(
            dara.String(templateID),
            &sandbox.DescribeTemplateCacheRequest{TeamID: dara.String(teamID)},
        )
        if err != nil {
            return fmt.Errorf("DescribeTemplateCache: %w", err)
        }

        cache = got.Body.TemplateCache
        status := dara.StringValue(cache.Status)
        fmt.Printf("status=%s progress=%d reason=%q sizeMB=%d requestId=%s\n",
            status,
            dara.Int32Value(cache.Progress),
            dara.StringValue(cache.StatusReason),
            dara.Int32Value(cache.ImageSizeMB),
            dara.StringValue(got.Body.RequestId),
        )

        switch status {
        case "ready":
            return nil
        case "failed", "evicted":
            return fmt.Errorf("template cache is %s: %s", status, dara.StringValue(cache.StatusReason))
        }
        time.Sleep(15 * time.Second)
    }
    return fmt.Errorf("timed out waiting for template cache")
}

Pre-warming is complete only when status is ready. progress is for display only. It takes only the values 0 (not ready) and 100 (ready), does not advance gradually as a percentage, and is not used to determine readiness.

Step 3: Create a sandbox from a pre-warmed template

After status is ready, use the template to create a sandbox so that the pre-warming speedup takes effect. If you create a sandbox before the pre-warming is complete, the only impact is that the speedup is usually unavailable. If the accelerated image data is still being prepared, a 400 accelerated image not ready error may be returned. Try again after the data is ready. For more information, see Create a Sandbox.

Query the pre-warming status

Call DescribeTemplateCache with the template ID and the Team ID, and determine the task status from the returned status:

• creating: The task is accepted and may be queuing, waiting for capacity, waiting for a concurrency slot, or pre-warming. Continue to query the task instead of creating it again.

• ready: The pre-warming is complete. Use the template to create a sandbox.

• failed: Pre-warming failed. Check statusReason to identify the cause, and then delete the task and create it again.

• evicted: The platform has reclaimed the pre-warmed data, so the task no longer provides the pre-warming speedup. Delete the task, wait until a query returns 404, and then create it again. Also delete the other evicted tasks of the same image (imageDigest) in the same region. Otherwise, the new task may immediately return to evicted.

Query pre-warming tasks with pagination

Call ListTemplateCache to paginate through the pre-warming tasks of the current Team. Filter the results by templateID and status. maxResults defaults to 20. Valid values range from 1 to 100. If the value is out of the range, the boundary value is used and no error is returned. Pagination ends when nextToken is empty. Do not determine the end of pagination from the number of entries on the current page.

Delete a pre-warming task

When pre-warming is no longer needed, call DeleteTemplateCache to delete the task.

func deleteCache(client *sandbox.Client, teamID, templateID string) error {
    resp, err := client.DeleteTemplateCache(
        dara.String(templateID),
        &sandbox.DeleteTemplateCacheRequest{TeamID: dara.String(teamID)},
    )
    if err != nil {
        return fmt.Errorf("DeleteTemplateCache: %w", err)
    }
    fmt.Printf("delete accepted: requestId=%s\n", dara.StringValue(resp.Body.RequestId))
    return nil
}

After DeleteTemplateCache returns success, continue to call DescribeTemplateCache until the call returns 404 TemplateCacheNotFound. The logical deletion of the pre-warming task is complete only after this error is returned. A successful response only indicates that the delete request is accepted. Once no live instance references the image, the platform safely and asynchronously cleans up the underlying image data. A repeated delete request returns 404.

To pre-warm a task again after its status becomes failed or evicted, delete the task first and then call CreateTemplateCache.