[Yandex Cloud documentation](../../index.md) > [Yandex StoreDoc](../index.md) > [Step-by-step guides](index.md) > Clusters > Yandex StoreDoc version update

# Yandex StoreDoc version upgrade

You can only upgrade your Yandex StoreDoc cluster to the next sequential version, e.g., from 4.2 to 4.4. Upgrading to subsequent versions must be done incrementally. For example, upgrading Yandex StoreDoc from version 4.2 to 8.0 is performed in the following sequence: 4.2 → 4.4 → 5.0 → 6.0 → 7.0 → 8.0. Before each cluster upgrade stage, you must update the [cluster compatibility version](#compatibility-update).


{% note alert %}

After the upgrade, it is impossible to revert the cluster to a previous version.

{% endnote %}

## Before version upgrade {#before-update}

1. Make sure the upgrade will not disrupt your applications:

1. Review the MongoDB release notes to learn how upgrades may affect your applications.
1. Try upgrading a test cluster. You can [deploy it from a backup](cluster-backups.md#restore) of the main cluster.
1. [Back up](cluster-backups.md#create-backup) your main cluster before upgrading.

1. Make sure the [cluster compatibility version](#compatibility-update) matches the current cluster version. If necessary, upgrade the cluster compatibility version.

## Upgrading the cluster version {#start-update}

{% list tabs group=instructions %}

- Management console {#console}

  1. Open the [folder dashboard](https://console.yandex.cloud).
  1. Navigate to **Yandex StoreDoc**.
  1. Select the cluster you need from the list and click **Edit**.
  1. Select the new version number in the **Version** field.
  1. Click **Save changes**.

  Once you launch the upgrade, the cluster status will change to **UPDATING**. Wait for the operation to complete and then check the cluster version.

- CLI {#cli}

  1. Retrieve the list of your Yandex StoreDoc clusters using this command:

     ```bash
     yc managed-mongodb cluster list
     ```

  1. Get the target cluster details and check the `config.version` setting for its Yandex StoreDoc version:

     ```bash
     yc managed-mongodb cluster get <cluster_name_or_ID>
     ```

  1. Start the Yandex StoreDoc upgrade:

     ```bash
     yc managed-mongodb cluster update <cluster_name_or_ID> \
        --mongodb-version=<new_version_number>
     ```

     Once you launch the upgrade, the cluster status will change to **UPDATING**. Wait for the operation to complete and then check the cluster version.

  1. After the upgrade, all non-backward-compatible Yandex StoreDoc features will be disabled. To remove this limitation, run the following command:

     ```bash
     yc managed-mongodb cluster update <cluster_name_or_ID> \
        --feature-compatibility-version=<new_version_number>
     ```


- Terraform {#tf}

    1. Open the current Terraform configuration file with the infrastructure plan.
  
       To learn how to create this file, see [Creating a cluster](cluster-create.md).
  
    1. Add or update the `version` field in the Yandex StoreDoc cluster description:
  
       ```hcl
       resource "yandex_mdb_mongodb_cluster" "<cluster_name>" {
         ...
         cluster_config {
           version = "<Yandex_StoreDoc_version>"
         }
       }
       ```

    1. Make sure the settings are correct.
  
         1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
         1. Run this command:
         
            ```bash
            terraform validate
            ```
         
            Terraform will show any errors found in your configuration files.
  
    1. Confirm updating the resources.
  
         1. Run this command to view the planned changes:
         
            ```bash
            terraform plan
            ```
         
            If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
         
         1. If everything looks correct, apply the changes:
            1. Run this command:
         
               ```bash
               terraform apply
               ```
         
            1. Confirm updating the resources.
            1. Wait for the operation to complete.
  
   For more information, see [this Terraform provider guide](../../terraform/resources/mdb_mongodb_cluster.md).

   {% note warning "Timeouts" %}
   
   The Terraform provider sets the following timeouts for Yandex StoreDoc cluster operations:
   
   * Creating a cluster, including by restoring one from a backup: 30 minutes.
   * Editing a cluster: 60 minutes.
   
   Operations exceeding the set timeout are interrupted.
   
   {% cut "How do I change these limits?" %}
   
   Add the `timeouts` block to the cluster description, for example:
   
   ```hcl
   resource "yandex_mdb_mongodb_cluster" "<cluster_name>" {
     ...
     timeouts {
       create = "1h30m" # An hour and a half
       update = "2h"    # Two hours
     }
   }
   ```
   
   {% endcut %}
   
   {% endnote %}

- REST API {#api}

   1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

   1. Call the [Cluster.Update](../api-ref/Cluster/update.md) method, e.g., via the following [cURL](https://curl.se/) request:

      {% note warning %}
      
      The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `updateMask` parameter as a single comma-separated string.
      
      {% endnote %}

      ```bash
      curl \
         --request PATCH \
         --header "Authorization: Bearer $IAM_TOKEN" \
         --header "Content-Type: application/json" \
         --url 'https://mdb.api.cloud.yandex.net/managed-mongodb/v1/clusters/<cluster_ID>' \
         --data '{
                  "updateMask": "configSpec.version",
                  "configSpec": {
                    "version": "<Yandex_StoreDoc_new_version>"
                  }
                }'
      ```

      Where:

      * `updateMask`: Comma-separated list of settings you want to update.

         Here, we provide only one setting.

      * `configSpec.version`: New Yandex StoreDoc version.

      You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

   1. Check the [server response](../api-ref/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
       
       ```bash
       cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
       ```
       
       Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

    1. Call the [ClusterService.Update](../api-ref/grpc/Cluster/update.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

        {% note warning %}
        
        The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `update_mask` parameter as an array of `paths[]` strings.
        
        {% cut "Format for listing settings" %}
        
        ```yaml
        "update_mask": {
            "paths": [
                "<setting_1>",
                "<setting_2>",
                ...
                "<setting_N>"
            ]
        }
        ```
        
        {% endcut %}
        
        {% endnote %}

        ```bash
        grpcurl \
            -format json \
            -import-path ~/cloudapi/ \
            -import-path ~/cloudapi/third_party/googleapis/ \
            -proto ~/cloudapi/yandex/cloud/mdb/mongodb/v1/cluster_service.proto \
            -rpc-header "Authorization: Bearer $IAM_TOKEN" \
            -d '{
                  "cluster_id": "<cluster_ID>",
                  "update_mask": {
                    "paths": [ 
                      "config_spec.version"
                    ]
                  },  
                  "config_spec": {
                    "version": "<Yandex_StoreDoc_version>"
                  }
               }' \
            mdb.api.cloud.yandex.net:443 \
            yandex.cloud.mdb.mongodb.v1.ClusterService.Update
        ```

        Where:

        * `update_mask`: List of settings you want to update as an array of strings (`paths[]`).

          Here, we provide only one setting.

        * `version`: New Yandex StoreDoc version.

        You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

    1. Check the [server response](../api-ref/grpc/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

{% note info %}

After the upgrade, all non-backward-compatible Yandex StoreDoc features will be disabled. To remove this limitation, [update the cluster compatibility version](#compatibility-update).

{% endnote %}

## Updating the cluster compatibility version {#compatibility-update}

Updating the cluster compatibility version is necessary when you need to:
* Upgrade your cluster to a new version (when the compatibility version does not match the current cluster version).
* Enable the new Yandex StoreDoc features after the cluster upgrade.

To learn more about backward compatibility, refer to the [MongoDB documentation](https://docs.mongodb.com/manual/reference/command/setFeatureCompatibilityVersion/).

{% note alert %}

Updating the cluster compatibility version is irreversible.

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. Open the [folder dashboard](https://console.yandex.cloud).
  1. Navigate to **Yandex StoreDoc**.
  1. Select the cluster you need from the list and click **Edit**.
  1. In the **Compatibility version** field, select the required version number.
  1. Click **Save changes**.

- CLI {#cli}

  1. Retrieve the list of your Yandex StoreDoc clusters using this command:

     ```bash
     yc managed-mongodb cluster list
     ```

  1. Get the target cluster details and check the `config.feature_compatibility_version` setting for its Yandex StoreDoc version:

     ```bash
     yc managed-mongodb cluster get <cluster_name_or_ID>
     ```

  1. Run the `cluster update` command, providing the new compatibility version:

     ```bash
     yc managed-mongodb cluster update <cluster_name_or_ID> \
        --feature-compatibility-version=<Yandex_StoreDoc_compatibility_version>
     ```

- Terraform {#tf}

    1. Open the current Terraform configuration file with the infrastructure plan.
  
       To learn how to create this file, see [Creating a cluster](cluster-create.md).
  
    1. Add or update the `feature_compatibility_version` field in the Yandex StoreDoc cluster description:
  
       ```hcl
       resource "yandex_mdb_mongodb_cluster" "<cluster_name>" {
         ...
         cluster_config {
           feature_compatibility_version = "<Yandex_StoreDoc_compatibility_version>"
         }
       }
       ```

    1. Make sure the settings are correct.
  
         1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
         1. Run this command:
         
            ```bash
            terraform validate
            ```
         
            Terraform will show any errors found in your configuration files.
  
    1. Confirm updating the resources.
  
         1. Run this command to view the planned changes:
         
            ```bash
            terraform plan
            ```
         
            If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
         
         1. If everything looks correct, apply the changes:
            1. Run this command:
         
               ```bash
               terraform apply
               ```
         
            1. Confirm updating the resources.
            1. Wait for the operation to complete.
  
   For more information, see [this Terraform provider guide](../../terraform/resources/mdb_mongodb_cluster.md).

   {% note warning "Timeouts" %}
   
   The Terraform provider sets the following timeouts for Yandex StoreDoc cluster operations:
   
   * Creating a cluster, including by restoring one from a backup: 30 minutes.
   * Editing a cluster: 60 minutes.
   
   Operations exceeding the set timeout are interrupted.
   
   {% cut "How do I change these limits?" %}
   
   Add the `timeouts` block to the cluster description, for example:
   
   ```hcl
   resource "yandex_mdb_mongodb_cluster" "<cluster_name>" {
     ...
     timeouts {
       create = "1h30m" # An hour and a half
       update = "2h"    # Two hours
     }
   }
   ```
   
   {% endcut %}
   
   {% endnote %}

- REST API {#api}

   1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

   1. Call the [Cluster.Update](../api-ref/Cluster/update.md) method, e.g., via the following [cURL](https://curl.se/) request:

      {% note warning %}
      
      The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `updateMask` parameter as a single comma-separated string.
      
      {% endnote %}

      ```bash
      curl \
         --request PATCH \
         --header "Authorization: Bearer $IAM_TOKEN" \
         --header "Content-Type: application/json" \
         --url 'https://mdb.api.cloud.yandex.net/managed-mongodb/v1/clusters/<cluster_ID>' \
         --data '{
                  "updateMask": "configSpec.featureCompatibilityVersion",
                  "configSpec": {
                    "featureCompatibilityVersion": "<Yandex_StoreDoc_compatibility_version>"
                  }
                }'
      ```

      Where:

      * `updateMask`: Comma-separated list of settings you want to update.

         Here, we provide only one setting.

      * `configSpec.featureCompatibilityVersion`: New Yandex StoreDoc compatibility version.

      You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

   1. Check the [server response](../api-ref/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
       
       ```bash
       cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
       ```
       
       Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

    1. Call the [ClusterService.Update](../api-ref/grpc/Cluster/update.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

        {% note warning %}
        
        The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `update_mask` parameter as an array of `paths[]` strings.
        
        {% cut "Format for listing settings" %}
        
        ```yaml
        "update_mask": {
            "paths": [
                "<setting_1>",
                "<setting_2>",
                ...
                "<setting_N>"
            ]
        }
        ```
        
        {% endcut %}
        
        {% endnote %}

        ```bash
        grpcurl \
            -format json \
            -import-path ~/cloudapi/ \
            -import-path ~/cloudapi/third_party/googleapis/ \
            -proto ~/cloudapi/yandex/cloud/mdb/mongodb/v1/cluster_service.proto \
            -rpc-header "Authorization: Bearer $IAM_TOKEN" \
            -d '{
                  "cluster_id": "<cluster_ID>",
                  "update_mask": {
                    "paths": [ 
                      "config_spec.feature_compatibility_version"
                    ]
                  },  
                  "config_spec": {
                    "feature_compatibility_version": "<Yandex_StoreDoc_compatibility_version>"
                  }
               }' \
            mdb.api.cloud.yandex.net:443 \
            yandex.cloud.mdb.mongodb.v1.ClusterService.Update
        ```

        Where:

        * `update_mask`: List of settings you want to update as an array of strings (`paths[]`).

          Here, we provide only one setting.

        * `feature_compatibility_version`: New Yandex StoreDoc compatibility version.

        You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

    1. Check the [server response](../api-ref/grpc/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Examples {#examples}

Suppose you need to upgrade a cluster from version 5.0 to 6.0.

{% list tabs group=instructions %}

- CLI {#cli}

   1. To get the cluster ID, retrieve a list of all clusters in your folder:

      ```bash
      yc managed-mongodb cluster list
      ```

      Result:

      ```text
      +----------------------+---------------+---------------------+--------+---------+
      |          ID          |     NAME      |     CREATED AT      | HEALTH | STATUS  |
      +----------------------+---------------+---------------------+--------+---------+
      | c9q8p8j2gaih******** |   storedoc406  | 2019-04-23 12:44:17 | ALIVE  | RUNNING |
      +----------------------+---------------+---------------------+--------+---------+
      ```

   1. To get `c9qut3k64b2o********` cluster details, run the following command:

      ```bash
      yc managed-mongodb cluster get c9qut3k64b2o********
      ```

      Result:

      ```text
      id: c9qut3k64b2o********
      folder_id: b1g0itj57rbj********
      created_at: "2019-07-16T09:43:50.393231Z"
      name: storedoc406
      environment: PRODUCTION
      monitoring:
      - name: Console
        description: Console charts
        link: https://console.yandex.cloud/folders/b1g0itj57rbj********/managed-mongodb/cluster/c9qut3k64b2o********?section=monitoring
      config:
        version: "5.0"
        feature_compatibility_version: "5.0"
        ...
      ```

   1. To upgrade the `c9qutgkd4b2o********` cluster to version 6.0, run this command:

      ```bash
      yc managed-mongodb cluster update c9qutgkd4b2o******** \
          --mongodb-version=6.0
      ```

   1. To enable all version 6.0 capabilities in the `c9qutgkd4b2o********` cluster, run this command:

      ```bash
      yc managed-mongodb cluster update c9qutgkd4b2o******** \
          --feature-compatibility-version=6.0
      ```

{% endlist %}