# 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. Under **Connected resources**, choose
   **Connect a resource**, then **Valkey cache** (offered 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. Leave **Redeploy now** on to apply it at once (offered with `deploy:DeployApp`), then choose
   **Bind cache**. The binding is listed under **Connected resources** with the variables it
   generates; its row's panel shows the private address.

**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 **Redeploy now** (`--redeploy`) the live deployment's
source is rolled out again with the new variables; otherwise 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`
