Bind a cache
Bind an app to a managed Valkey cache so that every rollout generates REDIS_URL and VALKEY_URL with the cache's private address.
Every rollout generates REDIS_URL and VALKEY_URL
(redis://default:<password>@<private address>:<port>, rediss:// for a cache with TLS), with a
prefix if you give one (SESSIONS_REDIS_URL). A highly available cache adds REDIS_READ_URL,
REDIS_SENTINELS and REDIS_SENTINEL_MASTER. The password is read from the cache at each rollout,
so nothing is stored with the app. An app has one cache binding per prefix: binding again with the
same prefix replaces the cache it points at. Replace app-id with the app's id and
ewc-0123456789ab with the cache's id.
Prerequisites
- A managed Valkey cache whose status is available. Every machine of the app must be in the cache's network; an app without machines yet can bind only a cache in the organization's default network, where its machines will run.
- Permission for
deploy:ManageCacheBindingon the app andcache:ModifyCacheClusteron the cache. To redeploy in the same step,deploy:DeployApp. - In the console, also
deploy:DescribeAppto open the app's page (without it the page is not found).
Bind the cache
- Open the app, then choose the Environment tab. The Cache section is shown only with
deploy:ManageCacheBinding. - For Cache, choose the cache. Only available caches are listed.
- (Optional) For Variable prefix, enter a prefix such as
SESSIONS_. - Choose Bind, or Bind & redeploy (shown only with
deploy:DeployApp). The binding is listed with its cache, its private address and the variables it generates.
dcloud deploy cache bind app-id --cache-cluster-id ewc-0123456789ab --redeployPUT /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/cache
{ "cacheClusterId": "ewc-0123456789ab", "envPrefix": "SESSIONS_", "redeploy": true }resource "dcloud_app_cache_binding" "sessions" {
app_id = dcloud_app.web.id
cache_cluster_id = dcloud_cache_cluster.sessions.id
env_prefix = "SESSIONS_"
}The binding is refused (409) when:
- the cache is not available yet (
The cache <id> is <status>; bind it once it is available) or has no private address; - a machine of the app is outside the cache's network (
The cache <id> is reachable only inside its network, and <machine> is not in it), or, for an app without machines, the cache is not in the default network; - the app's environment or a database binding already defines one of the generated variables
(
Remove <keys> from the environment first: the binding generates them); - the app is being deleted.
Unbind
In the binding's row choose Unbind, or run
dcloud deploy cache unbind app-id --env-prefix SESSIONS_ (leave out --env-prefix for a
binding without a prefix). The variables are left out of the next rollout; the cache is unchanged.
Result
Saving does not restart the app. With Bind & redeploy (--redeploy) the live deployment's
source is rolled out again with the new variables; otherwise the console says Not redeployed yet.
Redeploy to apply. and the variables reach the app with its next rollout.