> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/workspaces/storage-and-cloud-settings.md).

# Storage and cloud settings

Cloud Storage is configured once at workspace scope and then used from Data Space to create a connected cloud folder. Separate connection administration from the folder-level source scope that data operators actually import or synchronize.

### Before you make the change

* Create a dedicated organization-owned cloud identity with the minimum bucket and prefix permissions required.
* Record the connection owner, environment, rotation schedule, revocation procedure, and approved secret store.
* Confirm the current Unitlab connection mode and downstream source-availability requirements.

![Add Cloud Storage dialog for Amazon S3](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FEceeKlJexxGEUrAINYfa%2Fcloud-storage-add.png?alt=media\&token=7f2c7aff-bb2a-476f-87cb-a8bd3a70540f)

*Open Workspace Settings › Cloud storage and choose Add cloud storage. Select the provider and enter the display name, bucket, access key ID, secret access key, region, and optional prefix. Credentials in this product capture are intentionally blank.*

### Understand the product behavior

The current Add Cloud Storage dialog offers:

* Amazon S3;
* Google Cloud Storage;
* Azure Blob Storage;
* MinIO;
* DigitalOcean Spaces;
* Cloudflare R2;
* Wasabi;
* Backblaze B2;
* custom S3-compatible storage.

The exact credential fields vary by provider, but the current configuration model includes a display name, bucket or container, credentials, region where applicable, and an optional prefix or sub-path. A prefix can restrict Unitlab to a controlled part of a larger bucket.

The SDK can list safe storage metadata, browse a prefix, create a cloud-backed Unitlab folder, synchronize it, and import selected files or directory paths into a project. Cloud credentials are not returned by SDK list or browse operations.

### Cloud-folder user flow

Cloud folders are created from **New Folder ▾ → Add Cloud Folder**:

1. The user chooses a provider/integration.
2. The user selects an optional bucket sub-prefix and display name.
3. Unitlab creates a root folder representing that cloud location.
4. Opening it registers the first bucket level automatically if it has never been synchronized.
5. Immediate files appear as normal assets; child prefixes appear as child cloud folders.
6. The user can run **Sync** to refresh the current level.

Cloud folders reference customer storage; they do not copy the source bytes into Unitlab storage. Unitlab stores the object reference and a small preview where needed. Cloud folders display a provider badge, Synced state, and provider/resource path. Their contents are read-only mirrors for organization, so drag-move is disabled.

Cloud-folder Sync means “refresh this bucket prefix in Data Assets.” It is not project-to-dataset synchronization. A project receives cloud-backed content only through normal import/upload behavior or by attaching a frozen published dataset version.

### Connect and use cloud storage

{% stepper %}
{% step %}

#### 1. Open Cloud Storage settings

Confirm the active workspace, then open Settings › Cloud storage.
{% endstep %}

{% step %}

#### 2. Add the provider

Choose Add cloud storage and select the supported provider, such as Amazon S3.
{% endstep %}

{% step %}

#### 3. Enter the approved connection

Provide the display name, bucket name, access key ID, secret access key, region, and optional prefix. The prefix restricts the connection to a sub-path.
{% endstep %}

{% step %}

#### 4. Save and confirm Connected

Choose Add, wait for validation, and confirm the connection card shows the correct provider, bucket, region, creation date, and Connected status.
{% endstep %}

{% step %}

#### 5. Create a connected cloud folder

Go to Data Space › Assets, open New Folder, choose Add Cloud Folder, select the approved connection and exact source prefix, then create the folder.
{% endstep %}

{% step %}

#### 6. Reconcile source processing

Compare expected and processed counts, open representative assets, and review Batch Queue failures before dataset creation.
{% endstep %}

{% step %}

#### 7. Operate and rotate

Use Storage actions for approved lifecycle changes. Test a replacement credential before disabling or removing the old connection.
{% endstep %}

{% step %}

#### 8. Validate downstream behavior

Before changing the connection, confirm how existing assets, source references, stable URLs, and releases will behave.
{% endstep %}
{% endstepper %}

### Decisions that affect production

| Decision     | Production guidance                                                                                              |
| ------------ | ---------------------------------------------------------------------------------------------------------------- |
| Display name | Use a durable source-system and environment name that operators can distinguish.                                 |
| Prefix       | Restrict the connection to the smallest approved sub-path.                                                       |
| Identity     | Use a dedicated service identity, not a personal cloud credential.                                               |
| Lifecycle    | Changing or removing a connection can affect ingestion and later source retrieval; reconcile dependencies first. |
| Secrets      | Never place access keys, signed URLs, private bucket paths, or regulated filenames in documentation or logs.     |

{% hint style="warning" %}
The screenshot shows the field structure only. Never populate or publish a real access key ID, secret access key, private prefix, or signed URL in documentation.
{% endhint %}

### Continue the operating flow

* Create the connected cloud folder in Data Space.
* Curate the processed content inside that folder.
* Review credential ownership and rotation on schedule.