You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/app-service/overview-local-cache.md
+49-38Lines changed: 49 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,9 +9,20 @@ ms.date: 02/28/2025
9
9
ms.custom: UpdateFrequency3
10
10
ms.author: msangapu
11
11
author: msangapu-msft
12
-
12
+
ai-usage: ai-assisted
13
+
ms.collection: ce-skilling-ai-copilot
13
14
---
14
-
# Azure App Service Local Cache Overview
15
+
# Azure App Service local cache overview
16
+
17
+
> [!TIP]
18
+
>
19
+
> You can also ask Azure Copilot these questions:
20
+
>
21
+
> -*How does local cache work in app service?*
22
+
> -*What are the benefits of using local cache in Azure App Service?*
23
+
> -*What are the limitations of using local cache in Azure App Service?*
24
+
>
25
+
> To find Azure Copilot, on the [Azure portal](https://portal.azure.com) toolbar, select **Copilot**.
15
26
16
27
> [!NOTE]
17
28
> Local cache isn't supported in function apps or containerized App Service apps, such as in [Windows Containers](quickstart-custom-container.md?pivots=container-windows) or in [App Service on Linux](overview.md#app-service-on-linux). A version of local cache available for these app types is [App Cache](https://github.com/Azure-App-Service/KuduLite/wiki/App-Cache).
@@ -25,47 +36,47 @@ Azure App Service content is stored on Azure Storage and is exposed as a durable
25
36
26
37
While many apps use one or more of these features, some apps need a high-performance, read-only content store that they can run from with high availability. Such apps can benefit from running against a local cache on the VM instance.
27
38
28
-
The Azure App Service Local Cache feature provides a web role view of your content. This content is a write-but-discard cache of your storage content that is created asynchronously at site startup. Once the cache is ready, the site switches to run against the cached content. Apps running with Local Cache benefit in several ways:
39
+
The Azure App Service local cache feature provides a web role view of your content. This content is a write-but-discard cache of your storage content that is created asynchronously at site startup. Once the cache is ready, the site switches to run against the cached content. Apps running with local cache benefit in several ways:
29
40
30
41
* They are immune to latencies associated with accessing content on Azure Storage.
31
42
* They aren’t affected by connection issues to the storage, since the read-only copy is cached locally.
32
43
* They experience fewer app restarts due to changes in the storage share.
33
44
34
45
> [!NOTE]
35
-
> If you are using Java (Java SE, Tomcat, or JBoss EAP), then by default the Java artifacts—.jar, .war, and .ear files—are copied locally to the worker. If your Java application depends on read-only access to additional files, set `JAVA_COPY_ALL` to `true` so that those files are also copied. If Local Cache is enabled, it takes precedence over this Java-specific behavior.
46
+
> If you are using Java (Java SE, Tomcat, or JBoss EAP), then by default the Java artifacts—.jar, .war, and .ear files—are copied locally to the worker. If your Java application depends on read-only access to additional files, set `JAVA_COPY_ALL` to `true` so that those files are also copied. If local cache is enabled, it takes precedence over this Java-specific behavior.
36
47
37
-
## How Local Cache Changes the Behavior of App Service
48
+
## How local cache changes the behavior of App Service
38
49
39
50
***D:\home** now points to the local cache, which is created on the VM instance when the app starts. **D:\local** continues to point to the temporary, VM-specific storage.
40
51
* The local cache contains a one-time copy of the **/site** and **/siteextensions** folders from the shared content store, located at **D:\home\site** and **D:\home\siteextensions**, respectively. These files are copied to the local cache at app startup. The size of these two folders is limited to 1 GB by default but can be increased to 2 GB. As the cache size increases, it takes longer to load the cache. If you increase the local cache limit to 2 GB and the copied files exceed this maximum size, App Service silently ignores the local cache and reads from the remote file share.
41
52
> [!IMPORTANT]
42
-
> When the copied files exceed the defined Local Cache size limit—or when no limit is defined—deployment and swap operations may fail with an error. See the [FAQ](#frequently-asked-questions-faq) for more details.
53
+
> When the copied files exceed the defined local cache size limit—or when no limit is defined—deployment and swap operations may fail with an error. See the [FAQ](#frequently-asked-questions-faq) for more details.
43
54
>
44
55
* The local cache is read-write; however, any modifications are discarded when the app moves between VMs or restarts. Do not use the local cache for storing mission-critical data.
45
56
***D:\home\LogFiles** and **D:\home\Data** contain log files and app data. These folders are stored locally on the VM instance and are periodically copied to the shared content store. While apps can persist log files and data by writing to these folders, the copy process is best-effort. Consequently, log files and data may be lost if a VM instance crashes suddenly.
46
57
*[Log streaming](troubleshoot-diagnostic-logs.md#stream-logs) is impacted by this best-effort copy, and you might observe up to a one-minute delay in streamed logs.
47
-
* In the shared content store, the folder structure for **LogFiles** and **Data** changes for apps using Local Cache. There are now subfolders with names following the pattern "unique identifier" + timestamp, each corresponding to a VM instance where the app is or has been running.
58
+
* In the shared content store, the folder structure for **LogFiles** and **Data** changes for apps using local cache. There are now subfolders with names following the pattern "unique identifier" + timestamp, each corresponding to a VM instance where the app is or has been running.
48
59
* Other folders in **D:\home** remain in the local cache and aren’t copied to the shared content store.
49
60
* App deployments via any supported method publish directly to the durable shared content store. To refresh the **D:\home\site** and **D:\home\siteextensions** folders in the local cache, the app must be restarted. For a seamless lifecycle, see the information later in this article.
50
61
* The default content view of the SCM site continues to reflect the shared content store.
51
62
52
-
## Enable Local Cache in App Service
63
+
## Enable local cache in App Service
53
64
54
65
> [!NOTE]
55
-
> Local Cache isn't supported in the **F1** or **D1** tiers.
66
+
> Local cache isn't supported in the **F1** or **D1** tiers.
56
67
57
-
Local Cache is configured using a combination of reserved app settings. You can set these app settings using one of the following methods:
68
+
Local cache is configured using a combination of reserved app settings. You can set these app settings using one of the following methods:
Enable Local Cache on a per-web-app basis by adding this app setting:
76
+
Enable local cache on a per-web-app basis by adding this app setting:
66
77
`WEBSITE_LOCAL_CACHE_OPTION` = `Always`
67
78
68
-
### Configure Local Cache Using Azure Resource Manager
79
+
### Configure local cache using Azure Resource Manager
69
80
<aname="Configure-Local-Cache-ARM"></a>
70
81
71
82
```jsonc
@@ -88,56 +99,56 @@ Enable Local Cache on a per-web-app basis by adding this app setting:
88
99
...
89
100
90
101
91
-
## Change the Size SettinginLocal Cache
102
+
## Change the size settinginlocal cache
92
103
93
104
By default, the local cache size is **1GB**. This size includes the **/site** and **/siteextensions** folders copied from the content store, as well as any locally generated logs and data folders. To increase this limit, use the app setting `WEBSITE_LOCAL_CACHE_SIZEINMB`. You can increase the size up to **2GB** (2000MB) per app. Note that a larger cache size results in a longer cache load time.
94
105
95
-
## Best PracticesforUsing App Service Local Cache
106
+
## Best practicesforusing App Service local cache
96
107
97
-
We recommend using Local Cachein conjunction with the [Staging Environments](../app-service/deploy-staging-slots.md) feature.
108
+
We recommend using local cachein conjunction with the [Staging Environments](../app-service/deploy-staging-slots.md) feature.
98
109
99
110
* Add the sticky app setting `WEBSITE_LOCAL_CACHE_OPTION`with the value `Always` to your **Production**slot. If you're using `WEBSITE_LOCAL_CACHE_SIZEINMB`, mark it as a sticky setting for the Production slot as well.
100
-
* Create a **Staging** slot and publish to it. Typically, you do not set the Staging slot to use Local Cache, which helps enable a seamless build-deploy-test lifecycle while still providing Local Cache benefits for the Production slot.
111
+
* Create a **Staging** slot and publish to it. Typically, you do not set the Staging slot to use local cache, which helps enable a seamless build-deploy-test lifecycle while still providing local cache benefits for the Production slot.
101
112
* Test your site in the Staging slot.
102
113
* When ready, perform a [swap operation](../app-service/deploy-staging-slots.md#Swap) between the Staging and Production slots.
103
-
* Sticky settings are tied to the slot. Thus, when the Staging slot is swapped into Production, it inherits the Local Cache app settings. The newly swapped Production slot will run against the local cache after a few minutes and will be warmed up during slot warmup. Once the swap is complete, your Production slot will be running against the local cache.
114
+
* Sticky settings are tied to the slot. Thus, when the Staging slot is swapped into Production, it inherits the local cache app settings. The newly swapped Production slot will run against the local cache after a few minutes and will be warmed up during slot warmup. Once the swap is complete, your Production slot will be running against the local cache.
104
115
105
116
## Frequently Asked Questions (FAQ)
106
117
107
-
### What if the Local Cache Size Limit Is Exceeded?
108
-
If the copied files exceed the Local Cache size limit, the app will revert to reading from the remote share. However, deployment and swap operations may then fail with an error. See the table below for details.
118
+
### What if the local cache size limit is exceeded?
119
+
If the copied files exceed the local cache size limit, the app will revert to reading from the remote share. However, deployment and swap operations may then fail with an error. See the table below for details.
| ≤ 2 GB | ≤ Local Cache size | Reads from local cache. |
113
-
| ≤ 2 GB | > Local Cache size | Reads from remote share.<br/> **Note:** Deployment and swap operations may fail with an error. |
123
+
| ≤ 2 GB | ≤ local cache size | Reads from local cache. |
124
+
| ≤ 2 GB | > local cache size | Reads from remote share.<br/> **Note:** Deployment and swap operations may fail with an error. |
114
125
115
-
### How Can I Tell if Local Cache Applies to My App?
116
-
If your app requires a high-performance, reliable content store, does not use the content store for writing critical data at runtime, and the total size is less than 2 GB, then Local Cache is a good fit. To check the total size of your **/site** and **/siteextensions** folders, you can use the site extension "Azure Web Apps Disk Usage."
126
+
### How can I tell if local cache applies to my app?
127
+
If your app requires a high-performance, reliable content store, does not use the content store for writing critical data at runtime, and the total size is less than 2 GB, then local cache is a good fit. To check the total size of your **/site** and **/siteextensions** folders, you can use the site extension "Azure Web Apps Disk Usage."
117
128
118
-
### How Can I Tell if My Site Has Switched to Using Local Cache?
119
-
When using Local Cache with Staging Environments, the swap operation won’t complete until the Local Cache is warmed up. To verify that your site is running against Local Cache, check the worker process environment variable `WEBSITE_LOCALCACHE_READY`. Refer to the instructions on the [worker process environment variable](https://github.com/projectkudu/kudu/wiki/Process-Threads-list-and-minidump-gcdump-diagsession#process-environment-variable) page to inspect this variable across multiple instances.
129
+
### How can I tell if my site has switched to using local cache?
130
+
When using local cache with Staging Environments, the swap operation won’t complete until the local cache is warmed up. To verify that your site is running against local cache, check the worker process environment variable `WEBSITE_LOCALCACHE_READY`. Refer to the instructions on the [worker process environment variable](https://github.com/projectkudu/kudu/wiki/Process-Threads-list-and-minidump-gcdump-diagsession#process-environment-variable) page to inspect this variable across multiple instances.
120
131
121
-
### I Published New Changes, but My App Doesn’t Reflect Them. Why?
122
-
If your app uses Local Cache, you must restart the site to load the latest changes. If you prefer not to publish changes directly to your production site, consider using deployment slots as described in the best practices section above.
132
+
### I published new changes, but my app doesn’t reflect them. Why?
133
+
If your app uses local cache, you must restart the site to load the latest changes. If you prefer not to publish changes directly to your production site, consider using deployment slots as described in the best practices section above.
123
134
124
135
> [!NOTE]
125
-
> The [run from package](deploy-run-package.md) deployment option isn’t compatible with Local Cache.
136
+
> The [run from package](deploy-run-package.md) deployment option isn’t compatible with local cache.
126
137
127
-
### Where Are My Logs?
128
-
When using Local Cache, the structure of your log and data folders changes slightly. The subfolders are now nested under a folder named with the "unique VM identifier" and timestamp, corresponding to the VM instance where the app is or has been running.
138
+
### Where are my logs?
139
+
When using local cache, the structure of your log and data folders changes slightly. The subfolders are now nested under a folder named with the "unique VM identifier" and timestamp, corresponding to the VM instance where the app is or has been running.
129
140
130
-
### My App Still Gets Restarted Even with Local Cache Enabled. Why?
131
-
Local Cache helps prevent storage-related app restarts; however, your app may still restart during planned infrastructure upgrades on the VM. Overall, you should observe fewer restarts with Local Cache enabled.
141
+
### My app still gets restarted even with local cache enabled. Why?
142
+
local cache helps prevent storage-related app restarts; however, your app may still restart during planned infrastructure upgrades on the VM. Overall, you should observe fewer restarts with local cache enabled.
132
143
133
-
### Does Local Cache Exclude Any Directories from Being Copied to the Faster Local Drive?
144
+
### Does local cache exclude any directories from being copied to the faster local drive?
134
145
During the copy process, any folder named **repository** is excluded. This is useful in scenarios where your site content includes a source control repository that isn’t needed for day-to-day operations.
135
146
136
-
### How Do I Flush the Local Cache Logs After a Site Management Operation?
147
+
### How do I flush the local cache logs after a site management operation?
137
148
To flush the local cache logs, stop and restart the app. This action clears the previous cache.
138
149
139
-
### Why Does App Service Show Previously Deployed Files After a Restart When Local Cache Is Enabled?
140
-
If previously deployed files reappear after a restart, check for the presence of the App Setting `[WEBSITE_DISABLE_SCM_SEPARATION=true](https://github.com/projectkudu/kudu/wiki/Configurable-settings#use-the-same-process-for-the-user-site-and-the-scm-site)`. Adding this setting causes deployments via KUDU to write to the local VM instead of persistent storage. To avoid this, follow the best practices above and perform deployments to a staging slot that does not have Local Cache enabled.
150
+
### Why Does App Service show previously deployed files after a restart when local cache is enabled?
151
+
If previously deployed files reappear after a restart, check for the presence of the App Setting `[WEBSITE_DISABLE_SCM_SEPARATION=true](https://github.com/projectkudu/kudu/wiki/Configurable-settings#use-the-same-process-for-the-user-site-and-the-scm-site)`. Adding this setting causes deployments via KUDU to write to the local VM instead of persistent storage. To avoid this, follow the best practices above and perform deployments to a staging slot that does not have local cache enabled.
0 commit comments