Scale up the temporary storage space - Elastic Container Instance

Each Elastic Container Instance (ECI) pod includes 30 GiB of temporary storage space at no charge. If your workload needs more capacity, scale up the temporary storage space by setting an annotation or a resource request on the pod.

How it works

The 30 GiB default space is shared between the container image and your running workloads. Because ECI decompresses the image before use, the image occupies at least twice its compressed size. Subtract that from 30 GiB to estimate the space available to your containers. If the remaining space is insufficient, configure additional capacity — storage beyond the default 30 GiB is charged based on capacity and usage duration. For pricing details, see Billing of the temporary storage space.

Configuration methods

ECI supports two methods for scaling up temporary storage space. Use either method or both — if both are set, the greater value takes effect.

Method	Field	Syntax type	How scaled-up capacity is calculated
Annotation	`k8s.aliyun.com/eci-extra-ephemeral-storage`	Limit	Exactly the value you set
Resource request	`spec.containers[].resources.requests.ephemeral-storage`	Request	Value you set minus 30 GiB

The syntax difference matters: the annotation uses limit syntax, so the value directly equals the additional capacity. The resource request uses request syntax, so the value represents total desired capacity — ECI subtracts the 30 GiB default and allocates the remainder. For example, setting ephemeral-storage: 50Gi scales up by 20 GiB (50 − 30 = 20).

Method 1: Set an annotation

Add the k8s.aliyun.com/eci-extra-ephemeral-storage annotation to the pod metadata. The annotation value is the exact amount of additional storage to allocate.

Important

Add annotations to the pod metadata, not the Deployment metadata. For a Deployment, add the annotation under spec.template.metadata.annotations. Annotations take effect only at pod creation — modifying annotations on an existing pod has no effect.

Method 2: Set a resource request

Set spec.containers[].resources.requests.ephemeral-storage to the total storage capacity you need (default 30 GiB plus the additional capacity). Scale-up is triggered only when the value exceeds 30 GiB. The actual increase equals the specified value minus 30 GiB.

Note

When using Method 2, the actual scaled-up capacity may differ from your specified value depending on the image cache type. For details, see Image cache type and storage capacity.

Scale up the temporary storage space for a pod

Prerequisites

Before you begin, ensure that you have:

A Kubernetes cluster with ECI enabled (ACK or ASK)
kubectl configured to connect to your cluster

Step 1: Create the pod YAML file

Create a file named extra-storage.yaml. The following examples show how to scale up temporary storage space by 20 GiB using each method.

Example 1: Annotation

apiVersion: v1
kind: Pod
metadata:
  name: test
  annotations:
    k8s.aliyun.com/eci-extra-ephemeral-storage: "20Gi"  # Additional capacity beyond the default 30 GiB
spec:
  containers:
  - name: nginx
    image: registry-vpc.cn-beijing.aliyuncs.com/eci_open/nginx:1.14.2
    imagePullPolicy: IfNotPresent
  restartPolicy: Always

Example 2: Resource request

apiVersion: v1
kind: Pod
metadata:
  name: test
spec:
  containers:
  - name: nginx
    image: registry-vpc.cn-beijing.aliyuncs.com/eci_open/nginx:1.14.2
    imagePullPolicy: IfNotPresent
    resources:
      requests:
        ephemeral-storage: 50Gi  # Total capacity: 30 GiB default + 20 GiB additional
  restartPolicy: Always

Step 2: Create the pod

kubectl apply -f extra-storage.yaml

Step 3: Verify the configuration

Check the scaled-up capacity:

kubectl describe pod test | grep k8s.aliyun.com/eci-extra-ephemeral-storage

The following output confirms a 20 GiB scale-up:

k8s.aliyun.com/eci-extra-ephemeral-storage: 20Gi

Check the file system:

kubectl exec -it test -- sh
df -h

Expected output:

Filesystem      Size  Used Avail Use% Mounted on
overlay          50G  2.1G   48G   5% /
tmpfs            64M     0   64M   0% /dev
tmpfs           1.9G     0  1.9G   0% /sys/fs/cgroup
/dev/vda4        50G  2.1G   48G   5% /etc/hosts
shm              64M     0   64M   0% /dev/shm
tmpfs           4.0G   12K  4.0G   1% /run/secrets/kubernetes.io/serviceaccount
tmpfs           1.9G     0  1.9G   0% /proc/acpi
tmpfs           1.9G     0  1.9G   0% /sys/firmware

The overlay row shows the root file system. A size of 50G confirms the temporary storage space has been scaled up by 20 GiB (50 GiB total minus the 30 GiB default).

Image cache type and storage capacity

The disk that backs the temporary storage space depends on the image cache type used to create the pod.

Automatic image cache: temporary storage is on the system disk. The system disk partition (/dev/vda5) size equals the configured temporary storage capacity.
Manual image cache: temporary storage is on a data disk. The system disk partition (/dev/vda5) stays at the default 30 GiB and is not used for workload storage.

When using Method 2 (resource request) with a manual image cache, the actual allocated capacity may differ from your specified value because of how the data disk is provisioned.