# 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](/docs/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:ManageCacheBinding` on the app and `cache:ModifyCacheCluster` on the cache.
  To redeploy in the same step, `deploy:DeployApp`.
- In the console, also `deploy:DescribeApp` to open the app's page (without it the page is not
  found).

## Bind the cache

**Console**
1. Open the app, then choose the **Environment** tab. The **Cache** section is shown only with
   `deploy:ManageCacheBinding`.
2. For **Cache**, choose the cache. Only available caches are listed.
3. (Optional) For **Variable prefix**, enter a prefix such as `SESSIONS_`.
4. 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.

**CLI**
```sh
dcloud deploy cache bind app-id --cache-cluster-id ewc-0123456789ab --redeploy
```

**API**
```http
PUT /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/cache
{ "cacheClusterId": "ewc-0123456789ab", "envPrefix": "SESSIONS_", "redeploy": true }
```

**Terraform**
```hcl
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.

## Related

- [Bind a managed database](bind-a-database.md)
- `deploy.cache.bind` · `dcloud deploy cache bind` · `dcloud_app_cache_binding`
