[DOC] Update PUT Repository API documentation with Snapshot Interoperability w/ Remote Store related changes

[harishbhakuni]

What do you want to do?

• Request a change to existing documentation
• Add new documentation
• Report a technical problem with the documentation
• Other

Tell us about your request. Provide a summary of the request and all versions that are affected.
PUT Repository API Parameters: https://opensearch.org/docs/latest/api-reference/snapshots/create-repository/#request-parameters, https://opensearch.org/docs/latest/api-reference/snapshots/create-repository/#s3-repository

We need to add a new parameter for both S3 and fs Repository:

Request field	Description
remote_store_index_shallow_copy	Whether to take the snapshots of remote store enabled indices as shallow copy snapshots or not. Optional.

What other resources are available? Provide links to related issues, POCs, steps for testing, etc.
PR for changes in opensearch code: opensearch-project/OpenSearch#7118
Design Doc: opensearch-project/OpenSearch#6575

changes for this feature are already in 2.9 behind remote store experimental flag. to test, bring up the opensearch node with 2.9 version, enable remote store feature and then pass this in the Put Repository call, like this:

curl -X PUT "localhost:9200/_snapshot/shallowCopyRepository" -H 'Content-Type: application/json' -d'
{
  "type": "fs",
  "settings": {
    "location": "/mnt/snapshots",
    "base_path": "shallowCopy",
    "remote_store_index_shallow_copy": true
  }
}
'

[andrross]

@harishbhakuni21 What is the default value of this optional parameter? Also, how does this interact with the same parameter in the create snapshot API described in #4599?

[harishbhakuni]

@andrross So, during snapshot creation, we will check if this flag is present in repository settings or not, if it is present as true, we will take shallow copy snapshot else we will take full copy snapshot.
Also, default value of this parameter will be false.

[andrross]

@harishbhakuni21 Unless I'm misunderstanding, remote_store_index_shallow_copy can be defined as both a property of the repository (this issue) and as a parameter to the create snapshot API (issue #4599). We need to document the behavior of how these settings interact with one another. i.e. can the create snapshot parameter override the repository property? or is it the other way around?

[harishbhakuni]

@andrross i will make the wordings a bit more clear in these issues. but we will have this flag in Repository settings and in create snapshot API response, not in create snapshot API request. during snapshot creation, we will read repository setting property and use that. Will raise another issue for a detailed doc on usage of shallow copy snapshots.

[andrross]

Sorry, I had misread #4599 and now I see that the "shallow copy" field is just in the response. That makes sense, thanks @harishbhakuni21!

[harishbhakuni]

Hey, no worries @andrross, thanks for looking into this request.

[harishbhakuni]

tagging @hdhalter to help with the doc updates for Snapshot Interoperability w/ remote store.

Issues: #4598, #4599, #4600

[hdhalter]

@harishbhakuni - Hi Harish, are the two updates (#4599, #4600) targeting the 2.10 release, and this one is already implemented in 2.9?

[harishbhakuni]

@hdhalter yes we need all these in 2.10 release.

[Naarcha-AWS]

We'll address issues Issues: #4598, #4599, #4600 as a single PR. Will tag the PR in this issue when a draft is up.