[Yandex Cloud documentation](../../../index.md) > [Yandex Object Storage](../../index.md) > [Step-by-step guides](../index.md) > Objects > Managing object labels

# Managing object labels

An [object label](../../concepts/tags.md) is a key-value pair used for logical object labeling.

{% note info %}

Yandex Cloud uses _labels_ to logically identify resources. However, Object Storage supports compatibility with [Amazon S3 API](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html), that is why we use _tags_, a term native to AWS, in the [AWS CLI](../../tools/aws-cli.md) commands and [API](../../s3/index.md) parameters.

{% endnote %}

## Adding or updating labels {#add-edit-tag}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select a folder.
  1. Navigate to **Object Storage**.
  1. Select the bucket from the list.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/folder-tree.svg) **Objects**.
  1. Click the name of the object you need.
  1. Click **Add label**.
  1. Enter label key and value separated by a colon (key:value).

  To edit a label:
  
  1. Click **Add label**.
  1. Enter the key of the label you want to edit and its new value.

- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command for updating object labels in a bucket:

      ```bash
      yc storage s3api put-object-tagging --help
      ```

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

      ```bash
      yc storage bucket list
      ```

      Result:

      ```text
      +------------------+----------------------+-------------+-----------------------+---------------------+
      |       NAME       |      FOLDER ID       | MAX SIZE    | DEFAULT STORAGE CLASS |     CREATED AT      |
      +------------------+----------------------+-------------+-----------------------+---------------------+
      | my-bucket        | b1g5dk66rc1u******** | 53687091200 | STANDARD              | 2024-12-17 07:17:04 |
      +------------------+----------------------+-------------+-----------------------+---------------------+
      ```

  1. In the terminal, run this command that overwrites any existing object labels:

      ```bash
      yc storage s3api put-object-tagging \
        --bucket <bucket_name> \
        --key <object_key> \
        --version-id <version_ID> \
        --tagging TagSet=[{Key=<label_key>,Value=<label_value>},{Key=<label_key>,Value=<label_value>}]
      ```

      Where:
      * `--bucket`: Bucket name.
      * `--key`: Bucket object [key](../../concepts/object.md#key).
      * `--version-id`: Object [version](../../concepts/versioning.md). This is an optional setting.
      * `--tagging`: Array of object labels, where:
        * `Key`: Label key, the `string` type.
        * `Value`: Label value, the `string` type.

      Result:

      ```text
      request_id: ac9066e5********
      ```

- AWS CLI {#aws-cli}

  If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).

  In the terminal, run this command that overwrites any existing object labels:

  ```bash
  aws s3api put-object-tagging \
    --bucket <bucket_name> \
    --key <object_key> \
    --tagging 'TagSet=[{Key=<label_key>,Value=<label_value>},{Key=<label_key>,Value=<label_value>}]' \
    --endpoint-url=https://storage.yandexcloud.net
  ```

  Where:
  * `--bucket`: Bucket name.
  * `--key`: Bucket object [key](../../concepts/object.md#key).
  * `--tagging`: Array of object labels, where:
    * `Key`: Label key, the `string` type.
    * `Value`: Label value, the `string` type.
  * `--endpoint-url`: Object Storage endpoint.

- Terraform {#tf}

  {% note info %}
  
  If you access Object Storage via Terraform under a [service account](../../../iam/concepts/users/service-accounts.md), [assign](../../../iam/operations/sa/assign-role-for-sa.md) to the service account the relevant [role](../../security/index.md#roles-list), e.g., `storage.admin`, for the folder you are going to create the resources in.
  
  {% endnote %}

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../../terraform/authentication.md) using the appropriate method.


  1. Open the Terraform configuration file and add the `tags` section to the object description:

      ```hcl
      resource "yandex_storage_object" "test-object" {
        access_key       = "<static_key_ID>"
        secret_key       = "<secret_key>"
        bucket           = "<bucket_name>"
        key              = "<object_name>"
        source           = "<path_to_file>"
        tags             = {
          <label_1_key> = "<label_1_value>"
          <label_2_key> = "<label_2_value>"
        }
      }
      ```

      Where `tags` is the array of object labels in `<key> = "<value>"` format.
      
      For more information about the `yandex_storage_object` resource in Terraform, see [this TF provider article](../../../terraform/resources/storage_object.md).

  1. Apply the changes:

      1. In the terminal, navigate to the configuration file directory.
      1. Make sure the configuration is correct using this command:
      
         ```bash
         terraform validate
         ```
      
         If the configuration is valid, you will get this message:
      
         ```bash
         Success! The configuration is valid.
         ```
      
      1. Run this command:
      
         ```bash
         terraform plan
         ```
      
         You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
      1. Apply the configuration changes:
      
         ```bash
         terraform apply
         ```
      
      1. Type `yes` and press **Enter** to confirm the changes.

  This will add the specified labels to your object. You can check the new labels and the object settings using the [AWS CLI or S3 API](#get-tag).

- API {#api}

  To add or update object labels, use the [putObjectTagging](../../s3/api-ref/object/putobjecttagging.md) S3 API method.

{% endlist %}

## Viewing labels {#get-tag}

{% list tabs group=instructions %}

- Management console {#console}

  You can see the labels in the list of bucket objects and on the individual object's page.

  1. In the [management console](https://console.yandex.cloud), select a folder.
  1. Navigate to **Object Storage**.
  1. Select the bucket from the list.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/folder-tree.svg) **Objects**.
  1. Click the name of the object you need.


- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command for viewing object labels in a bucket:

      ```bash
      yc storage s3api get-object-tagging --help
      ```

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

      ```bash
      yc storage bucket list
      ```

      Result:

      ```text
      +------------------+----------------------+-------------+-----------------------+---------------------+
      |       NAME       |      FOLDER ID       | MAX SIZE    | DEFAULT STORAGE CLASS |     CREATED AT      |
      +------------------+----------------------+-------------+-----------------------+---------------------+
      | my-bucket        | b1g5dk66rc1u******** | 53687091200 | STANDARD              | 2024-12-17 07:17:04 |
      +------------------+----------------------+-------------+-----------------------+---------------------+
      ```

  1. Get information about object labels:

      ```bash
      yc storage s3api get-object-tagging \
        --bucket <bucket_name> \
        --key <object_key> \
        --version-id <version_ID>
      ```

      Where:
      * `--bucket`: Bucket name.
      * `--key`: Bucket object [key](../../concepts/object.md#key).
      * `--version-id`: Object [version](../../concepts/versioning.md). This is an optional setting.

      Result:

      ```text
      request_id: 2defc7b2********
      tag_set:
        - key: key-for-my-object-2
          value: second-value
        - key: key-for-my-object-1
          value: first-value
      ```

- AWS CLI {#aws-cli}

  If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).

  In the terminal, run this command:

  ```bash
  aws s3api get-object-tagging \
    --bucket <bucket_name> \
    --key <object_key> \
    --endpoint-url=https://storage.yandexcloud.net
  ```

  Where:
  * `--bucket`: Bucket name.
  * `--key`: Bucket object [key](../../concepts/object.md#key).
  * `--endpoint-url`: Object Storage endpoint.

  Result:

  ```json
  {
      "TagSet": [
          {
              "Key": "test-key-1",
              "Value": "test-value-1"
          },
          {
              "Key": "test-key-2",
              "Value": "test-value-2"
          }
      ]
  }
  ```

- API {#api}

  To view object labels, use the [getObjectTagging](../../s3/api-ref/object/getobjecttagging.md) S3 API method.

{% endlist %}

## Deleting labels {#delete-tag}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select a folder.
  1. Navigate to **Object Storage**.
  1. Select the bucket from the list.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/folder-tree.svg) **Objects**.
  1. Click the name of the object you need.
  1. Click the cross next to the label you want to delete.

- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command for deleting object labels in a bucket:

      ```bash
      yc storage s3api delete-object-tagging --help
      ```

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

      ```bash
      yc storage bucket list
      ```

      Result:

      ```text
      +------------------+----------------------+-------------+-----------------------+---------------------+
      |       NAME       |      FOLDER ID       | MAX SIZE    | DEFAULT STORAGE CLASS |     CREATED AT      |
      +------------------+----------------------+-------------+-----------------------+---------------------+
      | my-bucket        | b1g5dk66rc1u******** | 53687091200 | STANDARD              | 2024-12-17 07:17:04 |
      +------------------+----------------------+-------------+-----------------------+---------------------+
      ```

  1. Delete object labels from the bucket:

      ```bash
      yc storage s3api delete-object-tagging \
        --bucket <bucket_name> \
        --key <object_key> \
        --version-id <version_ID>
      ```

      Where:
      * `--bucket`: Bucket name.
      * `--key`: Bucket object [key](../../concepts/object.md#key).
      * `--version-id`: Object [version](../../concepts/versioning.md). This is an optional setting.

      Result:

      ```text
      request_id: 1131dfc4********
      ```

- AWS CLI {#aws-cli}

  If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).

  In the terminal, run this command:

  ```bash
  aws s3api delete-object-tagging \
    --bucket <bucket_name> \
    --key <object_key> \
    --endpoint-url=https://storage.yandexcloud.net
  ```

  Where:
  * `--bucket`: Bucket name.
  * `--key`: Bucket object [key](../../concepts/object.md#key).
  * `--endpoint-url`: Object Storage endpoint.

- Terraform {#tf}

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../../terraform/authentication.md) using the appropriate method.

  1. Open the Terraform configuration file and delete the `tags` section from the object description.

     {% cut "Example of an object label description in Terraform configuration" %}

     ```hcl
      resource "yandex_storage_object" "test-object" {
        ...
        tags             = {
          <label_1_key> = "<label_1_value>"
          <label_2_key> = "<label_2_value>"
        }
      }
     ...
     ```

     {% endcut %}

  1. Apply the changes:

      1. In the terminal, navigate to the configuration file directory.
      1. Make sure the configuration is correct using this command:
      
         ```bash
         terraform validate
         ```
      
         If the configuration is valid, you will get this message:
      
         ```bash
         Success! The configuration is valid.
         ```
      
      1. Run this command:
      
         ```bash
         terraform plan
         ```
      
         You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
      1. Apply the configuration changes:
      
         ```bash
         terraform apply
         ```
      
      1. Type `yes` and press **Enter** to confirm the changes.

  This will delete the object labels. You can check the label deletion and the object settings using the [AWS CLI or S3 API](#get-tag).

- API {#api}

  To delete object labels, use the [deleteObjectTagging](../../s3/api-ref/object/deleteobjecttagging.md) S3 API method.

{% endlist %}