Avere Azure Storage Cache Auto Import 2025-07-01 API Spec

[Aman-Jain-14]

ARM (Control Plane) API Specification Update Pull Request

Tip

Overwhelmed by all this guidance? See the Getting help section at the bottom of this PR description.

PR review workflow diagram

Please understand this diagram before proceeding. It explains how to get your PR approved & merged.

Purpose of this PR

What's the purpose of this PR? Check the specific option that applies. This is mandatory!

• New resource provider.
• New API version for an existing resource provider. (If API spec is not defined in TypeSpec, the PR should have been created in adherence to OpenAPI specs PR creation guidance).
• Update existing version for a new feature. (This is applicable only when you are revising a private preview API version.)
• Update existing version to fix OpenAPI spec quality issues in S360.
• Convert existing OpenAPI spec to TypeSpec spec (do not combine this with implementing changes for a new API version).
• Other, please clarify:
  • edit this with your clarification

Due diligence checklist

To merge this PR, you must go through the following checklist and confirm you understood
and followed the instructions by checking all the boxes:

• I confirm this PR is modifying Azure Resource Manager (ARM) related specifications, and not data plane related specifications.
• I have reviewed following Resource Provider guidelines, including
  ARM resource provider contract and
  REST guidelines (estimated time: 4 hours).
  I understand this is required before I can proceed to the diagram Step 2, "ARM API changes review", for this PR.

Additional information

Viewing API changes

For convenient view of the API changes made by this PR, refer to the URLs provided in the table
in the Generated ApiView comment added to this PR. You can use ApiView to show API versions diff.

Suppressing failures

If one or multiple validation error/warning suppression(s) is detected in your PR, please follow the
suppressions guide to get approval.

Getting help

• First, please carefully read through this PR description, from top to bottom. Please fill out the Purpose of this PR and Due diligence checklist.
• If you don't have permissions to remove or add labels to the PR, request write access per aka.ms/azsdk/access#request-access-to-rest-api-or-sdk-repositories
• To understand what you must do next to merge this PR, see the Next Steps to Merge comment. It will appear within few minutes of submitting this PR and will continue to be up-to-date with current PR state.
• For guidance on fixing this PR CI check failures, see the hyperlinks provided in given failure
  and https://aka.ms/ci-fix.
• For help with ARM review (PR workflow diagram Step 2), see https://aka.ms/azsdk/pr-arm-review.
• If the PR CI checks appear to be stuck in queued state, please add a comment with contents /azp run.
  This should result in a new comment denoting a PR validation pipeline has started and the checks should be updated after few minutes.
• If the help provided by the previous points is not enough, post to https://aka.ms/azsdk/support/specreview-channel and link to this PR.

[openapi-pipeline-app]

Next Steps to Merge

✅ All automated merging requirements have been met! To get your PR merged, see aka.ms/azsdk/specreview/merge.

[openapi-pipeline-app]

PR validation pipeline restarted successfully. If there is ApiView generated, it will be updated in this comment.

[azure-sdk]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
Swagger	Microsoft.StorageCache
Go	sdk/resourcemanager/storagecache/armstoragecache

[Aman-Jain-14]

@TimLovellSmith regarding adminStatus, yes we are mostly doing it for API consistency. AutoImport is a part of our HSM operation suite which has 5 operations:
Manual Import
Manual Export
Auto Export
Auto Import
Bi-Directional Sync

Out of those we have implemented and released 2 features already (Manual Import and Auto Export) and both of them use adminStatus.

[TimLovellSmith]

@TimLovellSmith regarding adminStatus, yes we are mostly doing it for API consistency. AutoImport is a part of our HSM operation suite which has 5 operations: Manual Import Manual Export Auto Export Auto Import Bi-Directional Sync

Out of them we have implemented and released 2 features already (Manual Import and Auto Export) and both of them use adminStatus.

Makes sense, I guess you can stick with that -- up to your team to figure out how to optimize the customer consistency pain versus usability.

[Aman-Jain-14]

@TimLovellSmith thank you so much for your detailed review and comments. For some reason GitHub doesn't let me reply to all the comments, so I'll try to summarise my responses here while categorising the comments to some degree:

Regarding x-ms-flatten, I've removed that qualifier from the blobSyncEvents subsection of the auto import status. Hopefully that will address the issues about fields under blobSyncEvents subsection.

I've replaced int32 with int64 for all the integer status fields.

Fixed the nextLink and value ordering.

Regarding AutoImport status vs. ProvisioningState, unfortunately users cannot look at ProvisioningState to understand the state of the job itself. ProvisioningState denotes if the job was able to start or if it failed during initial stage, i.e., the synchronous part of the job. Once the control plane receives the status that the data plane layer was able to successfully start the job and the job enters the long running asynchronous phase, the user needs to poll AutoImport status to know the current state of the job.

Regarding maximum-errors, there is no notion of retrying if an error is encountered. maximum-errors denotes the number of errors the long running auto import job will see, and still continue to progress and run. If the number of errors seen exceeds the maximum-errors given by user, the job reports a failure and is halted. We also noted that the idea of infinite is not appealing but a user can accept to not let any errors affect the progress of the auto import job itself while monitoring the logging container for the nature of the errors. Long running jobs can encounter a number of errors which may or may not affect the overall outcome of the job. This nature is also consistent with the same field defined in manual import.

Regarding json nature of autoImportPrefixes, we understand the concern but we have followed json formatting for similar fields in manual import and auto export features. File system admins are also more familiar and used to json formatting when using automated solutions like az cli, terraform etc.

Regarding letting users change some strategies/nature of the job later, we do not allow the nature of the job to be changed once it has started. The only field that the user can alter is adminStatus to disable the job itself. Once the job is disabled, it cannot be re-enabled. To change any of the user given parameters, the user will have to disable/delete the current job and start a new job with new set of parameters.

Regarding issues with the conflict resolution modes, I have updated the link that the users can refer to for a better/detailed understanding of the modes. We understand that these modes can seem convoluted but we have tried our best to explain them in the document leveraging some understanding on the user's part regarding the Lustre filesystem, HSM and AutoImport in general. Even the folks on the control plane team found it hard to grasp the nuances but as we talked more with the data plane team and their experience with other file system admins who held varying degree of understanding of the Lustre filesystem, the fields and their usage were in-line with the wider industry usage.

[microsoft-github-policy-service]

Hi, @@Aman-Jain-14. Your PR has no update for 14 days and it is marked as stale PR. If no further update for over 14 days, the bot will close the PR. If you want to refresh the PR, please remove no-recent-activity label.