# Set a storage quota

Cap how many bytes your organization's registry, or one repository, may store, so a push past the cap is refused.

Two caps apply besides the platform's registry storage quota (see [Quotas](quotas.md)):

- the **organization cap** counts the layers in repositories, each once however many repositories
  use it; the lower of it and the platform quota applies;
- a **repository cap** counts every layer that repository holds, shared with others or not.

Both are 1 MiB (1048576 bytes) to 1 PiB. Replace repository-id with the repository's id.

## Prerequisites

- For the organization cap: `ecr:PutRegistryStorageQuota`.
- For a repository cap: `ecr:UpdateRepository` on the repository, and in the console
  `ecr:DescribeRepositories` on it (without it the repository's page answers 404).

## Set the organization cap

**Console:** not available. The **Storage** page shows the cap but does not set it.

**CLI**
```sh
dcloud ecr storage put-quota --quota-bytes 107374182400
```

`dcloud ecr storage delete-quota` removes it.

**API**
```http
PUT /ecr/api/storage-quota
{ "quotaBytes": 107374182400 }
```

**Terraform**
```hcl
resource "dcloud_ecr_storage_quota" "this" {
  quota_bytes = 107374182400
}
```

The answer's `warning` says when the registry already stores more than the new cap: "The registry
already stores more than this: pushes are refused until images are deleted."

## Set a repository cap

**Console**
1. Open **Image repositories**, then open the repository.
2. Open the **Settings** tab.
3. Under **Storage**, choose **Set a cap** (or **Change cap**).
4. For **Cap (GiB)**, enter a size, such as `50`. Leave it empty to remove the cap.
5. Choose **Save cap** (or **Remove the cap**).

**CLI**
```sh
dcloud ecr repositories update repository-id --storage-quota-bytes 53687091200
```

**API**
```http
PATCH /ecr/api/repositories/repository-id
{ "storageQuotaBytes": 53687091200 }
```

**Terraform**
```hcl
resource "dcloud_ecr_repository" "my_app" {
  name                = "my-app"
  storage_quota_bytes = 53687091200
}
```

## Result

A push that would store more than a cap allows is refused with `DENIED`, and docker prints
`storage quota exceeded: … stores X of Y, and this adds Z — delete images, or raise the quota`. When
the platform's registry storage quota is the lower limit, the message starts with "Quota
exceeded: Registry storage" instead and says how to raise it. An
`ECR Storage Quota Exceeded` event goes to your event bus. Below the cap, a layer that is already
stored (in the organization, or for a repository cap in that repository) goes through. Once usage
has reached a cap, every new upload and every manifest push is refused, even for an image whose
layers are all stored. Pull-through cache fills count too, and restoring an expired image is
refused with `409` and code `QuotaExceeded` while a cap is full.

Lowering a cap below what is stored deletes nothing: new pushes are refused until images are
deleted. Layers held only by expired images do not count toward the organization cap.

## Related

- [Storage and cleanup](storage-and-cleanup.md)
- `ecr.storage.put-quota` · `dcloud ecr storage put-quota` · `dcloud_ecr_storage_quota`
