> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Buckets and storage

> Managed buckets and connections to external S3 storage, declared in an infrastructure or project link.

Buckets and external storage connections belong to your organization. You
can declare them in two places:

- An infrastructure link: one file per resource, `buckets/<name>.yaml` or
  `storages/<name>.yaml`. The file name is the resource's name.
- A project link: the `buckets` and `storages` lists of `project.yaml`, so
  an app team can manage its own buckets without an infrastructure link.

One resource is managed by one link. Declaring a resource another link
already manages is refused with `resource_managed_elsewhere`.

## Managed buckets

```yaml title="buckets/assets.yaml" iac tree=infra
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
quota_gb: 50
public_paths:
  - images/
domains:
  - assets.example.com
```

```yaml title="buckets/backups.yaml" iac tree=infra
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
quota_gb: 500
default_backup: true
```

| Key | Meaning |
| --- | --- |
| `quota_gb` | The quota in whole GB (1 GB = 10<sup>9</sup> bytes). Leaving it out leaves the quota as it is. |
| `public_paths` | Folders and objects anyone can read without credentials, at most 100. A present list replaces the stored one. |
| `domains` | Custom domains that serve the bucket. Each must be covered by a [verified domain](/iac/domains) of your organization. A present list replaces the stored one. |
| `default_backup` | Make this your organization's default backup bucket. Only in an infrastructure link. |
| `delete` | Delete the bucket, see [removing](#removing). |

In a project link, the same keys go in a list entry with a `name`:

```yaml title="projects/shop/project.yaml" iac tree=project
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
cluster: hetzner-fsn1
buckets:
  - name: shop-uploads
    quota_gb: 20
```

```yaml title="clusters/hetzner-fsn1.yaml" iac tree=project
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
pools:
  - name: control-plane
    role: control_plane
  - name: general
```

## External storage

A storage file connects an S3-compatible bucket you host elsewhere.

```yaml title="storages/archive.yaml" iac tree=infra
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
endpoint: https://s3.example.net
region: eu-central-1
bucket: archive
path_prefix: shop/
force_path_style: true
provider_hint: other
```

`provider_hint` is one of `aws`, `r2`, `wasabi`, `minio`, `backblaze`,
`hetzner` or `other`.

The file never holds credentials. A new connection waits for credentials
until someone enters the access key and secret in the dashboard. Until then,
references, bindings and backup targets that use it fail with
`storage_awaiting_credentials`: set the credentials, then sync again.

## Existing resources

Declaring a bucket or storage that already exists in your organization, and
that no link manages, adopts it: the link starts managing it and applies the
file's settings.

A `quota_gb` below what a bucket already stores is refused with
`quota_below_usage`.

## Removing

- Removing the file (or the list entry) stops managing the resource. It
  keeps existing, with its data. If other references in the same link still
  point at it, the change is refused with `ref_orphaned` until you remove
  them too.
- Keeping the file with `delete: true` deletes the resource. The deletion is
  [held](/iac/gitops#held) until someone confirms it by typing its name.

```yaml title="buckets/old-assets.yaml" iac tree=infra
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
delete: true
```

Renaming a file stops managing the old resource and creates a new one.

See the [bucket file reference](/iac/reference/bucket-file) and the
[storage file reference](/iac/reference/storage-file).
