From 06c0159137800c61a41b23cdddba68d181ec268b Mon Sep 17 00:00:00 2001 From: microzchang <110015819+microzchang@users.noreply.github.com> Date: Tue, 5 Sep 2023 06:01:49 +0000 Subject: [PATCH] Storage/Add instruction for setting up storage accounts (#4917) * update readme.md * update * fxi spell * update link * update link * update --------- Co-authored-by: Jinming Hu --- sdk/storage/README.md | 7 +++++-- sdk/storage/TestingGuide.md | 38 +++++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 2 deletions(-) create mode 100644 sdk/storage/TestingGuide.md diff --git a/sdk/storage/README.md b/sdk/storage/README.md index 795f31a6c..91840135f 100644 --- a/sdk/storage/README.md +++ b/sdk/storage/README.md @@ -14,9 +14,11 @@ Azure Storage is a Microsoft-managed service providing cloud storage that is hig ## Contributing -See the [Storage CONTRIBUTING.md][storage_contrib] for details on building, +See the [C++ Contributing Guide][sdk_contrib] for details on building, testing, and contributing to these libraries. +See the [Storage Testing Guide][storage_testing] for how to set up storage resources running unit tests. + This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For @@ -28,7 +30,8 @@ or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments. -[storage_contrib]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md +[sdk_contrib]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md +[storage_testing]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/TestingGuide.md [cla]: https://cla.microsoft.com [coc]: https://opensource.microsoft.com/codeofconduct/ [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ diff --git a/sdk/storage/TestingGuide.md b/sdk/storage/TestingGuide.md new file mode 100644 index 000000000..6235e8b6a --- /dev/null +++ b/sdk/storage/TestingGuide.md @@ -0,0 +1,38 @@ +# Setup Storage Resources for Running Unit Tests + +Storage accounts are required for running storage unit tests. We don't expect users or developers to do these configurations or run unit tests, unless you're making some major changes or working on new features. + +Azure Storage libraries for C++ offers three types for authorizing access to data: `Shared Key(storage account key)`, `Shared access signature (SAS)` and `Azure Active Directory (Azure AD)`. +The first two types can be obtained by `connection string`. + +#### Set up storage account +Before setting up storage account, you should have an overview of storage account: [Storage account overview][storage_account_overview]. + +Set up steps: +1. [Create storage account][create_storage_account] +2. [Get storage account connection string][get_connection_string] +3. Fill the connection strings in [source code](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-common/test/ut/test_base.cpp) or environment variables. + +| Environment Variable | Variable in Source Code | Storage Account Details | +|------------------------------------|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| STANDARD_STORAGE_CONNECTION_STRING | StandardStorageConnectionStringValue | Account Kind: General Purpose V2
Performance: Standard
Replication: RA-GRS
Enabled Features: soft delete for blobs, soft delete for containers, versioning for blobs | +| PREMIUM_FILE_CONNECTION_STRING | PremiumStorageConnectionStringValue | Account Kind: FileStorage
Performance: Premium
Replication: LRS | +| ADLS_GEN2_CONNECTION_STRING | AdlsGen2ConnectionStringValue | Account Kind: General Purpose V2
Performance: Standard
Replication: LRS
Enabled Features: hierarchical namespace | + +#### Set up Azure AD for storage account +Before setting it up, you should have an overview of accessing storage through Azure AD: [Authorize access to blobs using Azure Active Directory][access_azure_ad]. + +Set up steps: +1. [Create Azure Service Principal][create_service_principal]. +2. [Assign an Azure role for access to blob data][assign_role]. + - You can find storage roles in [Azure built-in roles][azure_built_in_roles] +3. Fill the tenant id, client id and client secret in environment variables or in source code. + + +[storage_account_overview]: https://learn.microsoft.com/azure/storage/common/storage-account-overview +[create_storage_account]: https://learn.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-portal +[get_connection_string]: https://learn.microsoft.com/azure/storage/common/storage-account-keys-manage?tabs=azure-portal#view-account-access-keys +[access_azure_ad]: https://learn.microsoft.com/azure/storage/blobs/authorize-access-azure-active-directory +[create_service_principal]: https://learn.microsoft.com/purview/create-service-principal-azure +[assign_role]: https://learn.microsoft.com/azure/storage/blobs/assign-azure-role-data-access?tabs=portal +[azure_built_in_roles]: https://learn.microsoft.com/azure/role-based-access-control/built-in-roles \ No newline at end of file