Skip to content

Commit 91e0f0b

Browse files
author
Xuyang Cao
committed
Add doc for BYOS as persistent storage feature
1 parent 8bdb717 commit 91e0f0b

File tree

2 files changed

+134
-9
lines changed

2 files changed

+134
-9
lines changed

‎articles/spring-cloud/how-to-persistent-storage.md renamed to ‎articles/spring-cloud/how-to-built-in-persistent-storage.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: How to use persistent storage in Azure Spring Cloud | Microsoft Docs
3-
description: How to use persistent storage in Azure Spring Cloud
2+
title: How to use built-in persistent storage in Azure Spring Cloud | Microsoft Docs
3+
description: How to use built-in persistent storage in Azure Spring Cloud
44
author: karlerickson
55
ms.service: spring-cloud
66
ms.topic: conceptual
@@ -9,11 +9,11 @@ ms.author: karler
99
ms.custom: devx-track-java, devx-track-azurecli
1010
---
1111

12-
# Use persistent storage in Azure Spring Cloud
12+
# Use built-in persistent storage in Azure Spring Cloud
1313

1414
**This article applies to:** ✔️ Java ✔️ C#
1515

16-
Azure Spring Cloud provides two types of storage for your application: persistent and temporary.
16+
Azure Spring Cloud provides two types of built-in storage for your application: persistent and temporary.
1717

1818
By default, Azure Spring Cloud provides temporary storage for each application instance. Temporary storage is limited to 5 GB per instance with the default mount path /tmp.
1919

@@ -25,7 +25,7 @@ Persistent storage is a file-share container managed by Azure and allocated per
2525
> [!WARNING]
2626
> If you disable an applications's persistent storage, all of that storage is deallocated and all of the stored data is lost.
2727
28-
## Use the Azure portal to enable persistent storage
28+
## Use the Azure portal to enable built-in persistent storage
2929

3030
1. From the **Home** page of your Azure portal, select **All Resources**.
3131

@@ -49,7 +49,7 @@ Persistent storage is a file-share container managed by Azure and allocated per
4949
5050
After persistent storage is enabled, its size and path are shown on the configuration page.
5151

52-
## Use the Azure CLI to modify persistent storage
52+
## Use the Azure CLI to modify built-in persistent storage
5353

5454
If necessary, install the Spring Cloud extension for the Azure CLI:
5555

@@ -59,19 +59,19 @@ az extension add --name spring-cloud
5959

6060
Other operations:
6161

62-
* To create an app with persistent storage enabled:
62+
* To create an app with built-in persistent storage enabled:
6363

6464
```azurecli
6565
az spring-cloud app create -n <app> -g <resource-group> -s <service-name> --enable-persistent-storage true
6666
```
6767
68-
* To enable persistent storage for an existing app:
68+
* To enable built-in persistent storage for an existing app:
6969
7070
```azurecli
7171
az spring-cloud app update -n <app> -g <resource-group> -s <service-name> --enable-persistent-storage true
7272
```
7373
74-
* To disable persistent storage in an existing app:
74+
* To disable built-in persistent storage in an existing app:
7575
7676
```azurecli
7777
az spring-cloud app update -n <app> -g <resource-group> -s <service-name> --enable-persistent-storage false

‎articles/spring-cloud/how-to-custom-persistent-storage.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Bring Your Own Storage (BYOS) to Azure Spring Cloud as extra persistent storages for applications | Microsoft Docs
3+
description: How to bring your own storage as persistent storages in Azure Spring Cloud
4+
author: Xuyang Cao
5+
ms.service: spring-cloud
6+
ms.topic: conceptual
7+
ms.date: 10/27/2021
8+
ms.author: xuycao
9+
ms.custom: devx-track-java, devx-track-azurecli
10+
---
11+
12+
# Bring Your Own Storage (BYOS) to Azure Spring Cloud as extra persistent storages for applications
13+
14+
**This article applies to:** ✔️ Java ✔️ C#
15+
16+
When you use the built-in persistent storage in Azure Spring Cloud, artifacts generated by your application are uploaded into Azure Storage Accounts. Microsoft controls the encryption-at-rest and lifetime management policies for those artifacts.
17+
18+
With Bring Your Own Storage, these artifacts are uploaded into a storage account that you control. That means you control the encryption-at-rest policy, the lifetime management policy and network access. You will, however, be responsible for the costs associated with that storage account.
19+
20+
## Prerequisites
21+
22+
* An existing Azure Storage Account with pre-created Azure File Share
23+
* The Azure Spring Cloud extension for the Azure CLI
24+
25+
## Use the Azure CLI to enable BYOS as extra persistent storages
26+
27+
1. Bind your Azure Storage Account as a storage resource in Azure Spring Cloud instance
28+
29+
```azurecli
30+
az spring-cloud storage add --storage-type StorageAccount --account-name <Your-Account-Name> --account-key <Your-Account-Key> -g <Resource-Group-Name> -s <Spring-Instance-Name> -n <Storage-Resource-Name>
31+
```
32+
33+
2. Create an app with BYOS persistent storages
34+
35+
```azurecli
36+
az spring-cloud app create -n <App-Name> -g <Resource-Group-Name> -s <Spring-Instance-Name> --persistent-storage "Path-To-JSON-File"
37+
```
38+
39+
> [!Note]
40+
> ```--persistent-storage``` accepts a path to a JSON file as the parameter.
41+
> Here is a sample JSON file:
42+
> ```json
43+
> {
44+
> "customPersistentDisks": [
45+
> {
46+
> "storageName": "<Storage-Resource-Name>",
47+
> "customPersistentDiskProperties": {
48+
> "type": "AzureFileVolume",
49+
> "shareName": "<Azure-File-Share-Name>",
50+
> "mountPath": "<Unique-Mount-Path e.g. /test/path>",
51+
> "mountOptions": [
52+
> "uid=0",
53+
> "gid=0",
54+
> ],
55+
> "readOnly": false
56+
> }
57+
> },
58+
> {
59+
> "storageName": "<Storage-Resource-Name>",
60+
> "customPersistentDiskProperties": {
61+
> "type": "AzureFileVolume",
62+
> "shareName": "<Azure-File-Share-Name>",
63+
> "mountPath": "<Unique-Mount-Path e.g. /test/anotherPath>",
64+
> "readOnly": true
65+
> }
66+
> }
67+
> ]
68+
>}
69+
> ```
70+
71+
3. [Optional] Append an extra persistent storage to an existing app
72+
73+
```azurecli
74+
az spring-cloud app append-persistent-storage --persistent-storage-type AzureFileVolume --share-name <Azure-File-Share-Name> --mount-path <Unique-Mount-Path e.g. /test/path> --storage-name <Storage-Resource-Name> -n <App-Name> -g <Resource-Group-Name> -s <Spring-Instance-Name>
75+
```
76+
77+
4. [Optional] List all existing persistent storages of a specific storage resource
78+
79+
```azurecli
80+
az spring-cloud storage list-persistent-storage -g <Resource-Group-Name> -s <Spring-Instance-Name> -n <Storage-Resource-Name>
81+
```
82+
## Best Practices
83+
- To avoid potential issues related to latency, it's a good choice to place the Azure Spring Cloud instance and the Azure Storage Account in the same Azure region.
84+
85+
- In the Azure Storage Account, avoid regenerating the account key that's being used. The storage account contains two different keys. Use a stepwise approach to ensure that the BYOS persistent storages remains available to the applications during key regeneration.
86+
87+
For example, assuming that you used key1 to bind storage account to Azure Spring Cloud:
88+
89+
1. Regenerate key2.
90+
2. Update the account key of storage resource to use the regenerated key2. And restart the applications that mounts persistent storages from this storage resource. (You can use ```az spring-cloud storage list-persistent-storage``` to list all related applications.)
91+
3. Regenerate key1.
92+
93+
- If you delete an Azure Storage Account or Azure File Share, remove the corresponding storage resource or persistent storages in the applications to avoid possible error scenarios.
94+
95+
## FAQs
96+
97+
1. If I have built-in persistent storage enabled, and then I enabled BYOS as extra persistent storage. Will my data be migrated into my Storage Account?
98+
99+
*No. But we are going to provide a doc to help you do the migration yourself in the near future.*
100+
101+
2. What are the reserved mount paths?
102+
103+
*These mount paths are reserved by Azure Spring Cloud service:*
104+
- "/tmp"
105+
- "/persistent"
106+
- "/secrets"
107+
- "/app-insights/agents"
108+
- "/etc/azure-spring-cloud/certs"
109+
- "/app-insights/agents/settings"
110+
- "/app-lifecycle/settings"
111+
112+
3. What are the available mount options?
113+
114+
*Now we only support the following mount options:*
115+
- "uid"
116+
- "gid"
117+
- "file_mode"
118+
- "dir_mode"
119+
120+
*The mountOptions property is optional. The default values for above mount options are: ["uid=0", "gid=0", "file_mode=0777", "dir_mode=0777"]*
121+
122+
## Next steps
123+
124+
* Learn about [application and service quotas](./quotas.md).
125+
* Learn how to [manually scale your application](./how-to-scale-manual.md).

0 commit comments

Comments
 (0)