--- title: "Getting started with Object Storage" description: "If you are using legacy Swift Object Storage, follow this guide." url: https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/getting-started lang: en --- > For AI agents: the complete documentation index is available at https://docs.us.ovhcloud.com/en/llms.txt, the full documentation bundle is available at https://docs.us.ovhcloud.com/en/llms-full.txt. # Getting started with Object Storage **Note:** If you are using legacy Swift Object Storage, follow [this guide](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/pcs-create-container.md). For new projects, we highly recommend using our S3™[\*](#go-further)-compatible Object Storage, which benefits from our latest innovations and new features.   ## Requirements - A [Public Cloud project](https://us.ovhcloud.com/public-cloud/) in your OVHcloud account - An [Object Storage user](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/identity-and-access-management.md) already created #### OVHcloud Control Panel Access - **Direct link:** [Public Cloud Projects](https://manager.us.ovhcloud.com/#/public-cloud/pci/projects) - **Navigation path:** `Public Cloud` > Select your project   ## Instructions **Note:** If you wish to use the OVHcloud Terraform provider, see our [Manage an Object Storage bucket with Terraform](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/terraform.md) guide. ### Preparation #### To use the AWS CLI To find out how to install the AWS CLI in your environment, we recommend you read the [official AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions). #### Check installation ```bash aws --version ``` **Note:** If you need more information about AWS CLI installation, read the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).   #### Collect Credentials - Retrieve your user's Access key _and_ Secret key. You can retrieve this information from the [OVHcloud Control Panel](https://manager.us.ovhcloud.com/) under `Public Cloud` > `Object Storage` > `Users`. - You will also need your _endpoint\_url_ and the _region_. If you have already created your container, find this information in the `My containers` tab in the details of your container. If needed, see our [Object Storage - Endpoints and geoavailability](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/endpoints-geoavailability.md) guide.   #### Where to find the Endpoint URL of a container Click the `name` of the container and then the `General information` tab.   #### Configuration Use the interactive configuration to generate the configuration files, or create them manually. **Note:** To use the interactive configuration, run the following command: `aws --configure` or `aws configure --profile ` The configuration file format in the AWS client is as follows: ```bash cat ~/.aws/credentials [default] aws_access_key_id = aws_secret_access_key = ``` ```bash cat ~/.aws/config [default] region = endpoint_url = services = ovh-us-east-va-archive [profile ] region = us-east-va output = json services = ovh-us-east-va [services ovh-us-east-va-archive] s3 = endpoint_url = https://s3.us-east-va-archive.io.cloud.ovh.us/ signature_version = s3v4 s3api = endpoint_url = https://s3.us-east-va-archive.io.cloud.ovh.us/ [services ovh-us-east-va] s3 = endpoint_url = https://s3.us-east-va.io.cloud.ovh.us/ signature_version = s3v4 s3api = endpoint_url = https://s3.us-east-va.io.cloud.ovh.us/ ``` Here are the configuration values you can set: | **Variable** | **Type** | **Value** | **Definition** | | ------------------------- | -------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | max\_concurrent\_requests | Integer | **Default:** 10 | The maximum number of simultaneous requests. | | max\_queue\_size | Integer | **Default:** 1000 | The maximum number of tasks in the task queue. | | multipart\_threshold | Integer String | **Default:** 8 MB | The size threshold that the CLI uses for multipart transfers of individual files. | | multipart\_chunksize | Integer String | **Default:** 8 MB **Minimum for uploads:** 5 MB | When using multipart transfers, this is the byte size that the CLI uses for multipart transfers of individual files. | | max\_bandwidth | Integer | **Default:** None | The maximum bandwidth that will be used to load and download data to and from your buckets. | | verify\_ssl | Boolean | **Default:** true | Enable / Disable SSL certificate verification | For a list of endpoints by region and storage class, see the [Object Storage - Endpoints and geoavailability](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/endpoints-geoavailability.md) guide.   #### Usage **Note:** If you have more than one profile, add `--profile ` to the command line. ##### Using the OVHcloud Control Panel To manage an Object Storage bucket, navigate to `Object Storage` in the left-hand menu.   ### Listing your buckets #### Via the AWS CLI #### Via AWS s3 ```bash aws s3 ls ``` #### Via AWS S3API ```bash aws s3api list-buckets --query "Buckets[].Name" # Remove --query to display the full output. ``` ##### Via the OVHcloud Control Panel Click on `Object Storage` in the navigation bar on the left and then on the `My containers` tab. ##### Via the OVHcloud CLI **Note:** See our [Getting Started with OVHcloud CLI](https://docs.us.ovhcloud.com/en/manage-and-operate/cli/getting-started-ovhcloud-cli.md) guide to learn about the OVHcloud CLI. Enter the following command: ``` ovhcloud cloud storage-s3 list ```   ### Create a bucket #### Via the AWS CLI #### Via AWS s3 ```bash aws s3 mb s3:// aws --profile s3 mb s3:// ``` #### Via AWS S3API ```bash aws s3api create-bucket --bucket aws s3api create-bucket --bucket --profile default ``` ##### Via the OVHcloud Control Panel Click `+ Create an object container`. You can enter the name of your bucket (optional) and then **select your offer**. **Select a deployment mode.** OVHcloud provides multiple deployment modes to meet different needs in terms of resilience, availability and performance. Each mode is optimized for specific use cases and offers varying levels of redundancy and fault tolerance. **Select a region.** Regions can vary depending on the chosen deployment mode. You can then set the configuration parameters for your bucket. At this stage, you can decide whether or not to enable **versioning**. Versioning allows you to keep multiple variants of an object in the same bucket. This feature helps **preserve, retrieve, and restore every version of every object stored in your buckets**, making it easier to recover from unintended user actions or application failures. By default, versioning is disabled on buckets; enable it if needed. For more information about versioning, see our [Object Storage - Getting started with versioning](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/versioning.md) guide. You can also enable [Object Lock](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/managing-object-lock.md) to store your objects in WORM (Write Once, Read Many) mode and guarantee their immutability for a defined retention period. **Warning:** **NOTE:** This option must be enabled when creating a bucket, it cannot be enabled later. You must link a user to the bucket. To do this, you can either: - Link an existing Object Storage user. To check the credentials, click on `View credentials`. - Or create a new Object Storage user. You can now decide whether or not you wish to **encrypt your data** using [SSE-OMK (server-side encryption with OVHcloud Managed Keys)](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/encrypt-your-objects-with-sse-c.md). Once you have finished configuring your bucket, click `Create`. ##### Via the OVHcloud CLI **Note:** See our [Getting Started with OVHcloud CLI](https://docs.us.ovhcloud.com/en/manage-and-operate/cli/getting-started-ovhcloud-cli.md) guide to learn about the OVHcloud CLI. Enter the following command, replacing `` with your region code (e.g., `US-EAST-VA`) and `` with the desired name: ``` ovhcloud cloud storage-s3 create --name ``` To create a bucket with versioning and encryption enabled: ``` ovhcloud cloud storage-s3 create --name --versioning-status enabled --encryption-sse-algorithm AES256 ``` To create a bucket with Object Lock enabled: ``` ovhcloud cloud storage-s3 create --name --object-lock-status enabled --object-lock-rule-mode compliance --object-lock-rule-period P30D ``` **Note:** The `--object-lock-status enabled` option must be set at bucket creation time; it cannot be enabled later.   ### Uploading your files as objects in your bucket When uploading objects, select a storage class to control availability, redundancy, and cost. To help you choose the right storage class for your needs, see the [Choosing the right storage class for your needs](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/choosing-the-right-storage-class-for-your-needs.md) guide. #### Via the AWS CLI **Note:** The `aws s3 cp` command will use STANDARD as default storage class for uploading objects. To store objects in the High Performance tier, use the `aws s3api put-object` command instead, as `aws s3 cp` does not support the EXPRESS\_ONEZONE storage class, which is used to map the High Performance storage tier. To learn more about the storage class mapping between OVHcloud storage tiers and AWS storage classes, you can check our documentation [here](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/endpoints-geoavailability.md). #### Via AWS s3 **To upload an object:** ```bash aws s3 cp /data/ s3:// ``` **By default, objects are named after files, but can be renamed:** ```bash aws s3 cp /data/ s3:///other-filename ``` ##### Via the OVHcloud Control Panel Click on the `name of your container`, then click `+ Add objects`. You can add a prefix to your object name (the object name is the same as the file name). Select the storage class. Finally, select the file you are about to download and click on the `Import` button.   ### Downloading an object from a bucket #### Via the AWS CLI #### Via AWS s3 **Downloading an object from a bucket:** ```bash aws s3 cp s3:/// . ``` **Uploading an object from one bucket to another bucket:** ```bash aws s3 cp s3:/// s3:/// ``` **Downloading or uploading an entire bucket to the host/bucket:** ```bash aws s3 cp s3:// . --recursive aws s3 cp s3:// s3:// --recursive ``` #### Via AWS S3API **Downloading an object from a bucket:** ```bash aws s3api get-object --bucket --key ``` **Uploading an object from one bucket to another bucket:** ```bash aws s3api copy-object --bucket --copy-source / --key ``` ##### Via the OVHcloud Control Panel Click on the _download_ icon to the right of the object.   ### Synchronizing buckets #### Via AWS CLI ```bash aws s3 sync . s3:// # Synchronizing local directory to the S3 bucket aws s3 sync s3:// . # Synchronizing S3 bucket to the local directory aws s3 sync s3:// s3:// # Synchronizing an S3 bucket to another one ```   ### Deleting objects and buckets **Note:** A bucket can only be deleted if it is empty. #### Via the AWS CLI **Note:** If your bucket has Object Lock enabled, you will not be able to permanently delete your objects. See our [documentation](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/managing-object-lock.md) to learn more about Object Lock. If you use Object Lock in GOVERNANCE mode and have the permission to bypass GOVERNANCE mode, you will have to add the `--bypass-governance-retention` option to your delete commands. #### Via AWS s3 **To delete an object:** ```bash aws s3 rm s3:/// ``` **To remove all objects from a bucket:** ```bash aws s3 rm s3:// --recursive ``` **To delete a bucket, it must be empty:** ```bash aws s3 rb s3:// ``` If the bucket is not removed, you can use the same command with the `--force` option. This deletes all objects from the bucket, and then deletes the bucket. ```bash aws s3 rb s3:// --force ``` **Deleting objects and buckets with versioning enabled:** If versioning is enabled, a standard delete operation on your objects will not permanently remove them. To permanently delete an object, you must specify a version ID: ```bash aws s3api delete-object --bucket --key --version-id ``` To list all objects and their version IDs, you can use the following command: ```bash aws s3api list-object-versions --bucket ``` With the above delete-object command, you will have to iterate over all your object versions. You can also use the following one-liner to empty your bucket: ```bash aws s3api delete-objects --bucket --delete "$(aws s3api list-object-versions --bucket --query='{Objects: Versions[].{Key:Key,VersionId:VersionId}}')" ``` #### Via AWS S3API **Deleting objects and buckets:** ```bash # Delete an object aws s3api delete-object --bucket --key # Removing all objects from a bucket aws s3api delete-objects --bucket --delete "$(aws s3api list-objects-v2 --bucket --query='{Objects: Contents[].{Key:Key}}')" # Delete a bucket. To delete a bucket, it must be empty. aws s3api delete-bucket --bucket ``` **Deleting objects and buckets with versioning enabled:** If versioning is enabled, a standard delete operation on your objects will not permanently delete them. To permanently delete an object, you need to specify a version identifier: ```bash aws s3api delete-objects --bucket --delete "$(aws s3api list-object-versions --bucket --query='{Objects: Versions[].{Key:Key,VersionId:VersionId}}')" ``` ##### Via the OVHcloud Control Panel **Deleting a bucket:** In the list of object storage containers, click the _more options_ `...` button to the right, then select `Delete`. Type `TERMINATE` to confirm your choice, and click `Confirm`. **Deleting objects:** Go to the `Objects` tab of the relevant bucket and click the _Delete_ `🗑️` icon to the right of the object line. Type `PERMANENTLY DELETE` to confirm your choice, and click on `Delete`. ##### Via the OVHcloud CLI **Note:** See our [Getting Started with OVHcloud CLI](https://docs.us.ovhcloud.com/en/manage-and-operate/cli/getting-started-ovhcloud-cli.md) guide to learn about the OVHcloud CLI. **Deleting objects** ``` # Delete an object ovhcloud cloud storage-s3 object delete # Delete all objects in a bucket ovhcloud cloud storage-s3 bulk-delete --all # Delete objects matching a prefix ovhcloud cloud storage-s3 bulk-delete --prefix # Delete specific objects ovhcloud cloud storage-s3 bulk-delete --objects "file1.txt,file2.txt" ``` **Deleting a bucket** The bucket must be empty before deletion. ``` ovhcloud cloud storage-s3 delete ``` **Deleting objects with versioning enabled** If versioning is enabled, specify the version ID to permanently delete an object: ``` ovhcloud cloud storage-s3 object version delete ``` To delete all versions of an object, combine the version list and deletion: ``` ovhcloud cloud storage-s3 bulk-delete --objects "myfile.txt:,myfile.txt:" ```   ### Manage tags #### Via the AWS CLI #### Via AWS S3API **Setting tags on a bucket:** ```bash aws s3api put-bucket-tagging --bucket --tagging 'TagSet=[{Key=myKey,Value=myKeyValue}]' aws s3api get-bucket-tagging --bucket ``` ```json { "TagSet": [ { "Value": "myKeyValue", "Key": "myKey" } ] } ``` **Deleting tags on a bucket:** ```bash aws s3api delete-bucket-tagging --bucket ``` **Setting tags on an object:** ```bash aws s3api put-object-tagging --bucket --key --tagging 'TagSet=[{Key=myKey,Value=myKeyValue}]' aws s3api get-bucket-tagging --bucket ``` ```json { "TagSet": [ { "Value": "myKeyValue", "Key": "myKey" } ] } ``` **Deleting tags on an object:** ```bash aws s3api delete-object-tagging --bucket --key ``` ##### Via the OVHcloud CLI **Note:** See our [Getting Started with OVHcloud CLI](https://docs.us.ovhcloud.com/en/manage-and-operate/cli/getting-started-ovhcloud-cli.md) guide to learn about the OVHcloud CLI. The OVHcloud CLI lets you set tags on a bucket at **creation** time or when **editing** it via the `--tag key=value` option (repeatable for multiple tags). Individual tag management (reading, deleting) is not available via the CLI. **Setting tags when creating a bucket** ``` ovhcloud cloud storage-s3 create --name --tag myKey=myKeyValue --tag otherKey=otherValue ``` **Updating tags on an existing bucket** ``` ovhcloud cloud storage-s3 edit --tag myKey=myKeyValue ```   ## Go further Browse all the [Object Storage (S3™-compatible) guides](https://docs.us.ovhcloud.com/en/storage-and-backup/object-storage/landing-page-object-storage.md). Browse the rest of the [OVHcloud US documentation](https://docs.us.ovhcloud.com/en/index.md) for guides on our other products and services. Learn more about [Object Storage](https://us.ovhcloud.com/public-cloud/object-storage/) on the OVHcloud US website. \*S3 is a trademark filed by Amazon Technologies, Inc. OVHcloud's service is not sponsored by, endorsed by, or otherwise affiliated with Amazon Technologies, Inc.