> 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/data/cloud-providers.md).

# Cloud providers

Connected storage keeps large or governed source collections in their approved system of record while Unitlab registers and processes the content required for data production.

### Before you make the change

* Use an organization-owned cloud identity with least privilege.
* Identify the exact bucket, container, prefix, and ownership boundary.
* Agree how credentials are stored, rotated, revoked, and audited.

![Workspace Add Cloud Storage dialog](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)

*The connection is created in Workspace Settings › Cloud storage. After it shows Connected, return to Data Space › Assets and use New Folder › Add Cloud Folder to choose the connection and exact source scope.*

### 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.

### A safe cloud-connection pattern

For enterprise use, the connection should be treated as infrastructure, not as a convenient personal login:

1. Create a dedicated read-only or least-privilege identity for Unitlab.
2. Restrict it to the required bucket/container and prefix.
3. Avoid root or account-wide credentials.
4. Test with a small non-sensitive prefix.
5. Confirm that files, metadata, nested paths, and synchronization behave as expected.
6. Record the source system and connection owner.
7. Separate permission to manage cloud connections from permission to annotate data.

Workspace administrators can create, update, delete, test, and browse cloud connections from Workspace Settings. Connection administration requires cloud-storage permission and should remain separate from ordinary data browsing or annotation.

### Register a cloud source safely

{% stepper %}
{% step %}

#### 1. Create the connection

Select the provider and enter the approved connection details without exposing secrets in tickets or screenshots.
{% endstep %}

{% step %}

#### 2. Test access

Confirm Unitlab can enumerate only the intended storage scope.
{% endstep %}

{% step %}

#### 3. Browse to the prefix

Select the exact folder or object set; pay attention to provider-specific prefix behavior.
{% endstep %}

{% step %}

#### 4. Import the selection

Choose the destination and start registration or copy according to the connection mode.
{% endstep %}

{% step %}

#### 5. Reconcile results

Compare expected and processed counts, inspect representative items, and review Batch Queue failures.
{% endstep %}

{% step %}

#### 6. Record ownership

Document the source scope, identity owner, rotation process, and removal procedure.
{% endstep %}
{% endstepper %}

### Decisions that affect production

| Decision         | Production guidance                                                                             |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| Identity         | Prefer a dedicated service identity over a personal user credential.                            |
| Scope            | Grant the smallest bucket or prefix required for the use case.                                  |
| Change control   | Treat provider, prefix, permission, and credential changes as production configuration changes. |
| Failure handling | Retry only after checking remote state so the operation is idempotent.                          |

{% hint style="warning" %}
Never place cloud secrets, signed URLs, or private source paths in public documentation, screenshots, comments, or logs.
{% endhint %}

### Continue the operating flow

* Validate recognized file families.
* Apply Data folder and metadata conventions.
* Review access when the source or owner changes.