Contact UsTry it for free
© 2025 Direct Cursus Technology L.L.C.

Uploading an object

Written by
Improved by
Updated at December 12, 2025

You can create folders within a bucket and upload objects to them. Keep in mind that in the SDK and HTTP API, an object key is the entire path to the object from the bucket root. For more information, see Object.

Note

You can upload objects of up to 5 GB via the management console (see Quotas and limits in Object Storage). When uploading via the console, you cannot specify content-type or other headers. To upload larger objects or specify object headers, use other tools.

You can use tools that support Object Storage and signed URLs to upload objects into a bucket.

Regular uploads

To work with objects in an encrypted bucket, a user or service account must have the following roles for the encryption key in addition to the storage.configurer role:

  • kms.keys.encrypter: To read the key, encrypt and upload objects.
  • kms.keys.decrypter: To read the key, decrypt and download objects.
  • kms.keys.encrypterDecrypter: This role includes the kms.keys.encrypter and kms.keys.decrypter permissions.

For more information, see Key Management Service service roles.

  1. In the management console, select a folder.
  2. Go to Object Storage.
  3. Select the bucket to upload the object into.
  4. In the left-hand panel, select Objects.
  5. If you want to upload an object to the bucket for the first time, click Upload objects.
  6. If you want to upload the object to a specific folder, navigate to that folder by clicking its name. If you need to create a new folder, click Create folder.
  7. Within the folder you need, click Upload on the top panel.
  8. In the window that opens, select the files and click Open.
  9. The management console will display all the objects you selected for uploading and prompt you to select a storage class. The bucket configuration determines the default storage class.
  10. Click Upload.
  11. Refresh the page.

In the management console, the information about the number of objects and storage space used in the bucket is updated with a few minutes' delay.

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

  1. See the description of the CLI command for uploading a file to a bucket:

    yc storage s3api put-object --help

  2. Get a list of buckets in the default folder:

    yc storage bucket list

    Result:

    +------------------+----------------------+-------------+-----------------------+---------------------+
|       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
+------------------+----------------------+-------------+-----------------------+---------------------+
| first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  3. Run this command:

    yc storage s3api put-object \
  --body <local_file_path> \
  --bucket <bucket_name> \
  --key <object_path>

    Where:

    • --body: Path to the file you need to upload to the bucket.
    • --bucket: Name of your bucket.
    • --key: Key to use for storing the object in the bucket.

    Result:

    etag: '"d41d8cd98f00b204e980099********"'
request_id: 3f2705f********

    Alternative command:

    yc storage s3 cp \
  <local_file_path> \
  s3://<bucket_name>/<object_path>

    Result:

    upload: object.txt to s3://my-bucket/object.txt
    Configuring parameters for the yc storage s3 cp command

    You can set the following parameters for the yc storage s3 cp command:

    • s3.max-queue-size: Maximum number of issues per queue. The default value is 1,000.
    • s3.max-concurrent-requests: Maximum number of simultaneous requests. The default value is 10.
    • s3.multipart-threshold: Object threshold size to trigger a multipart upload if exceeded. The default value is 8MB.
    • s3.multipart-chunksize: Size of parts the object will be split into in a multipart upload. The default value is 8MB.

    To set these parameters, use the yc config set <parameter> <value> command.

  1. If you do not have the AWS CLI yet, install and configure it.

  2. To upload a single object, run this command:

    aws --endpoint-url=https://storage.yandexcloud.net/ \
  s3 cp <local_file_path> s3://<bucket_name>/<object_key>

    Where:

    • --endpoint-url: Object Storage endpoint.
    • s3 cp: Command to upload an object. To upload an object, in the first part of the command, provide the path to the local file you want to upload, and in the second part, the name of your bucket and the object storage key.

    To load all objects from the local directory, use the following command:

    aws --endpoint-url=https://storage.yandexcloud.net/ \
  s3 cp --recursive <path_to_local_directory>/ s3://<bucket_name>/<prefix>/

    Where:

    • --endpoint-url: Object Storage endpoint.
    • s3 cp --recursive: Command to upload all objects stored in a local directory, including the nested ones. To upload objects, in the first part of the command, provide the path to the folder from which you want to copy the files to the bucket, and in the second part, the name of your bucket and storage folder ID.

aws s3 cp is a high-level command providing limited features. For more information, see the AWS CLI reference. All upload features Object Storage supports can be used when running the aws s3api put-object command (see examples of using object locks below).

Note

Terraform uses a service account to interact with Object Storage. Assign to the service account the required role, e.g., storage.admin, for the folder where you are going to create resources.

With Terraform, you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

Terraform is distributed under the Business Source License. The Yandex Cloud provider for Terraform is distributed under the MPL-2.0 license.

For more information about the provider resources, see the relevant documentation on the Terraform website or its mirror.

If you do not have Terraform yet, install it and configure the Yandex Cloud provider.

Before you start, retrieve the static access keys: a secret key and key ID used for Object Storage authentication.

Note

In addition to static access keys, you can use an IAM token for authentication in Object Storage. For more details, see Creating a bucket and the relevant provider documentation.

To create an object in an existing bucket:

  1. In the configuration file, describe the resources you want to create:

    # Creating a service account

resource "yandex_iam_service_account" "sa" {
  name = "<service_account_name>"
}

# Assigning roles to a service account

resource "yandex_resourcemanager_folder_iam_member" "sa-admin" {
  folder_id = "<folder_ID>"
  role      = "storage.admin"
  member    = "serviceAccount:${yandex_iam_service_account.sa.id}"
}

# Creating a static access key

resource "yandex_iam_service_account_static_access_key" "sa-static-key" {
  service_account_id = yandex_iam_service_account.sa.id
  description        = "static access key for object storage"
}

# Create object

resource "yandex_storage_object" "test-object" {
  access_key = yandex_iam_service_account_static_access_key.sa-static-key.access_key
  secret_key = yandex_iam_service_account_static_access_key.sa-static-key.secret_key
  bucket     = "<bucket_name>"
  key        = "<object_name>"
  source     = "<path_to_file>"
}

    Where:

    • access_key: Static access key ID.

    • secret_key: Secret access key value.

    • bucket: Name of the bucket to add the object to. This is a required setting.

    • key: Name of the object in the bucket. This is a required setting. Follow these naming requirements:

      • It must be from 2 to 63 characters long.
      • It can only contain lowercase Latin letters, numbers, and hyphens.
      • It must start with a letter and cannot end with a hyphen.

    • source: Relative or absolute path to the file you need to upload to the bucket.

    For more information about the resources you can create with Terraform, see this provider guide.

Uploading an object version with an object lock

For a bucket with enabled versioning and object lock, you can define object lock settings (disable deleting or overwriting) when uploading an object version.

  1. In the management console, select a folder.
  2. Go to Object Storage.
  3. Select the bucket to upload the object into.
  4. In the left-hand panel, select Objects.
  5. If you want to upload an object to the bucket for the first time, click Upload objects.
  6. If you want to upload the object to a specific folder, navigate to that folder by clicking its name. If you want to create a new folder, click Create folder on the top panel.
  7. Within the folder you need, click Upload on the top panel.
  8. In the window that opens, select the files and click Open.
  9. The management console will display all the objects you selected for uploading and prompt you to select a storage class. The bucket configuration determines the default storage class.
  10. To configure locks for the objects you are uploading, select the lock type from the Object version lock drop-down list:
    • Legal hold: Indefinitely prohibits deleting or overwriting the object version, while you still can upload new versions of the object. A user with the storage.uploader role can set and remove legal hold. There is no way to bypass this type of lock. When combined with retention, legal hold takes priority.
    • Retention: Prohibits deleting or overwriting the object version for a specified period of time, while you still can upload new versions of the object. A user with the storage.uploader role can set a retention period. When combined with legal hold, retention takes no priority.
  11. If you selected Retention, specify Default lock type:
    • Governance: User with the storage.admin role can bypass the lock, change its expiration date, or remove it.
    • Compliance: User with the storage.admin role can only extend the retention period. You cannot override, shorten, or remove such locks until they expire.
  12. Specify Default lock period in days or years. It starts from the moment you upload the object version to the bucket.
  13. Click Upload and refresh the page.

In the management console, the information about the number of objects and storage space used in the bucket is updated with a few minutes' delay.

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

  1. See the description of the CLI command for uploading a file to a bucket:

    yc storage s3api put-object --help

  2. Get a list of buckets in the default folder:

    yc storage bucket list

    Result:

    +------------------+----------------------+-------------+-----------------------+---------------------+
|       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
+------------------+----------------------+-------------+-----------------------+---------------------+
| first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  3. Run this command:

    yc storage s3api put-object \
 --body <local_file_path> \
 --bucket <bucket_name> \
 --key <object_key> \
 --object-lock-mode <retention_type> \
 --object-lock-retain-until-date <retention_end_date_and_time> \
 --object-lock-legal-hold-status <legal_hold_status>

    Where:

    • --body: Path to the file you need to upload to the bucket.

    • --bucket: Name of your bucket.

    • --key: Key by which to store the object in the bucket.

    • --object-lock-mode: Type of retention:

      • GOVERNANCE: Governance-mode retention.
      • COMPLIANCE: Compliance-mode retention.

    • --object-lock-retain-until-date: Retention end date and time in any format described in the HTTP standard, such as 2025-01-02T15:04:05Z. You can only specify it together with the --object-lock-mode parameter.

    • --object-lock-legal-hold-status: Legal hold status:

      • ON: Enabled.
      • OFF: Disabled.

    For an object version, you can use either retention (the object-lock-mode and object-lock-retain-until-date parameters), legal hold (object-lock-legal-hold-status), or both. For more information about their combined use, see Object lock types.

    Result:

    etag: '"d41d8cd98f00b204e9800998********"'
request_id: e19afe50********
version_id: 0006241E********

  1. If you do not have the AWS CLI yet, install and configure it.

  2. Run this command:

    aws --endpoint-url=https://storage.yandexcloud.net/ \
  s3api put-object \
  --body <local_file_path> \
  --bucket <bucket_name> \
  --key <object_key> \
  --object-lock-mode <retention_type> \
  --object-lock-retain-until-date <retention_end_date_and_time> \
  --object-lock-legal-hold-status <legal_hold_status>

    Where:

    • --endpoint-url: Object Storage endpoint.
    • s3api put-object: Command to upload an object version. To upload object versions with an object lock, specify the following parameters:

      • --body: Path to the file you need to upload to the bucket.

      • --bucket: Name of your bucket.

      • --key: Key by which to store the object in the bucket.

      • --object-lock-mode: Type of retention:

        • GOVERNANCE: Governance-mode retention.
        • COMPLIANCE: Compliance-mode retention.

      • --object-lock-retain-until-date: Retention end date and time in any format described in the HTTP standard, e.g., Mon, 12 Dec 2022 09:00:00 GMT. You can only specify it together with the --object-lock-mode parameter.

      • --object-lock-legal-hold-status: Legal hold status:

        • ON: Enabled.
        • OFF: Disabled.

    For an object version, you can use either retention (the object-lock-mode and object-lock-retain-until-date parameters), legal hold (object-lock-legal-hold-status), or both. For more information about their combined use, see Object lock types.

To upload an object version with a lock, use the upload S3 API method with the X-Amz-Object-Lock-Mode and X-Amz-Object-Lock-Retain-Until-Date headers to apply a retention period and X-Amz-Object-Lock-Legal-Hold to put a legal hold.

If your bucket already has default retention periods configured, specify the relevant MD5 hash for any object you upload to the bucket:

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

  1. Determine the file’s MD5 hash and encode it with Base64:

    md5=($(md5sum <local_file_path>))
md5_base64=$(echo $md5 | base64)

  2. See the description of the CLI command for uploading a file to a bucket:

    yc storage s3api put-object --help

  3. Get a list of buckets in the default folder:

    yc storage bucket list

    Result:

    +------------------+----------------------+-------------+-----------------------+---------------------+
|       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
+------------------+----------------------+-------------+-----------------------+---------------------+
| first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  4. Upload an object to the bucket:

     yc storage s3api put-object \
  --body <local_file_path> \
  --bucket <bucket_name> \
  --key <object_key> \
  --content-md5 $md5_base64

    Where:

    • --body: Path to the file you need to upload to the bucket.
    • --bucket: Name of your bucket.
    • --key: Key by which to store the object in the bucket.
    • --content-md5: Object's encoded MD5 hash.

    You can also add the following parameters to the command:

    • --object-lock-mode and --object-lock-retain-until-date to set a retention period for an object version that overrides the bucket's default retention settings.
    • --object-lock-legal-hold-status to set a legal hold on an object version.

    For more information about these parameters, see the steps above.

  1. Determine the file’s MD5 hash and encode it with Base64:

    md5=($(md5sum <local_file_path>))
md5_base64=$(echo $md5 | base64)

  2. If you do not have the AWS CLI yet, install and configure it.

  3. Upload an object to the bucket:

    aws --endpoint-url=https://storage.yandexcloud.net/ \
  s3api put-object \
  --body <local_file_path> \
  --bucket <bucket_name> \
  --key <object_key> \
  --content-md5 $md5_base64

    Where:

    • --endpoint-url: Object Storage endpoint.
    • s3api put-object: Command to upload an object version. To upload object versions, specify the following parameters:
      • --body: Path to the file you need to upload to the bucket.
      • --bucket: Name of your bucket.
      • --key: Key by which to store the object in the bucket.
      • --content-md5: Object's encoded MD5 hash.

    You can also add the following parameters to the command:

    • --object-lock-mode and --object-lock-retain-until-date to set a retention period for an object version that overrides the bucket's default retention settings.
    • --object-lock-legal-hold-status to set a legal hold on an object version.

    For more information about these parameters, see the steps above.

To upload an object version with a default retention period, use the upload S3 API method with the Content-MD5 header.

Object conditional writes

You can use conditions when uploading an object, as well as when completing a multipart upload.

Uploading an object with an ETag condition

  1. If you do not have the AWS CLI yet, install and configure it.

  2. To upload an object only if an object with a certain ETag exists, run this command:

    aws s3api put-object \
    --endpoint-url https://storage.yandexcloud.net \
    --body <local_file_path> \
    --bucket <bucket_name> \
    --key <object_path> \
    --if-match "<object_ETag>"

    Where:

    • --endpoint-url: Object Storage endpoint.
    • --body: Path to the file you need to upload to the bucket, e.g., ./my-folder/my-file.txt.
    • --bucket: Name of your bucket.
    • --key: Key by which to store the object in the bucket. For example: my-folder/my-file.txt.
    • --if-match: Current object ETag, e.g., \"d41d8cd98f00b204e9800998********\". The write will only be performed if an object already exists for the specified key and its current ETag matches.

To upload an object only if an object with a certain ETag exists, use the upload S3 API method with the --if-match header.

Uploading an object with an absence condition

  1. If you do not have the AWS CLI yet, install and configure it.

  2. To upload an object only if there is no object with a specific key in the bucket, run this command:

    aws s3api put-object \
    --endpoint-url https://storage.yandexcloud.net \
    --body <local_file_path> \
    --bucket <bucket_name> \
    --key <object_path> \
    --if-none-match "*"

    Where:

    • --endpoint-url: Object Storage endpoint.
    • --body: Path to the file you need to upload to the bucket, e.g., ./my-folder/my-file.txt.
    • --bucket: Name of your bucket.
    • --key: Key by which to store the object in the bucket. For example: my-folder/my-file.txt.
    • --if-none-match: Type "*" to perform the write only if there is no object with the specified key yet.

To upload an object only if the bucket does not contain an object with a specific key, use the upload S3 API method with the --if-none-match header.

See also

Previous
Viewing bucket metrics
Next
Multipart upload of an object