During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in
Provisioning Azure Cache for Redis
This guide shows you how to provision an Azure Cache for Redis against Locally, and then connect to it with redis-cli to write and read a key. As with the other guides we're going to use the Azure CLI, but the same resource can be provisioned with HashiCorp Terraform, Pulumi or Bicep too.
Before you start
- The Azure CLI (
az) installed. redis-cliinstalled, version 6 or later so that it can connect over TLS. It ships with Redis itself.- Locally installed, with Locally Setup completed.
1. Start Locally
Firstly, we need to launch Locally which we can do from a terminal by running:
$
locally build
Once Locally has started, the Locally Dashboard will open automatically:
2. Create a Resource Group
Next we can create the Resource Group to hold the cache:
$
locally run az group create -n sample-redis -l berlin
There's two things to note here:
- The Azure CLI supports Automatic Configuration, meaning that it can automatically be configured to work against Locally just by prefixing commands with
locally run. - Locally intentionally uses a different set of locations to Azure as a safety precaution, so that you can be confident you're deploying against Locally rather than regular Azure. You can also configure Locally to use the Azure locations too, but you'll want to be extra sure that you're prefixing commands with
locally runwhen you do.
3. Create the cache
With the Resource Group in place, we can create the cache itself. We'll use the smallest size, a Basic C0:
$
locally run az redis create --name sampleredisdocs1 --resource-group sample-redis --location berlin --sku Basic --vm-size c0
Note
Behind the scenes Locally starts a real Redis server in a container. The parts of the response we care about are the hostName and the sslPort:
{
"note": "some fields skipped for brevity",
"enableNonSslPort": false,
"hostName": "sampleredisdocs1.redis.locally",
"name": "sampleredisdocs1",
"provisioningState": "Succeeded",
"sslPort": 58248,
"type": "Microsoft.Cache/redis"
}
That redis.locally hostname is served by Locally's own DNS server, and Locally handles TLS and the access key check in front of the container. Azure always uses port 6380 for TLS, but Locally picks a free port for each cache - so read sslPort from the response rather than hard-coding it.
We can retrieve the cache again at any point with:
$
locally run az redis show --name sampleredisdocs1 --resource-group sample-redis --query "{name:name, hostName:hostName, sslPort:sslPort, provisioningState:provisioningState, sku:sku.name}"
Which gives us:
{
"hostName": "sampleredisdocs1.redis.locally",
"name": "sampleredisdocs1",
"provisioningState": "Succeeded",
"sku": "Basic",
"sslPort": 58248
}
4. Get the access key
Connecting to the cache needs one of its access keys:
$
locally run az redis list-keys --name sampleredisdocs1 --resource-group sample-redis
{
"primaryKey": "X/ELqExtxgvkhZJ5gq9gBuJn9PW3eD8SRzK56AuXPOg8",
"secondaryKey": "y8j8WQ50/xJeg/R9u4Gns74vRKCfHBlFueViZnFl8Wta"
}
Rather than copying values around, locally redis connection-string puts the hostname, port and primary key together into a URL that redis-cli understands. Let's keep hold of it:
$
export REDIS_URL=$(locally redis connection-string --name sampleredisdocs1)
Note
locally redis is part of Locally itself, so it doesn't take the locally run prefix. Every az command does.5. Connect with redis-cli
Now we can talk to the cache. Locally's certificates are signed by its own local CA, so we point redis-cli at that with --cacert. Let's write a key:
$
redis-cli -u "$REDIS_URL" --cacert ~/.config/locally/local-ca.pem SET greeting "hello from Locally"
OK
And read it back:
$
redis-cli -u "$REDIS_URL" --cacert ~/.config/locally/local-ca.pem GET greeting
hello from Locally
The URL starts with rediss://, so redis-cli connects over TLS without needing --tls. It also prints a warning that the password is on the command line, which is fine for a sample like this one.
Leave off SET or GET to get an interactive prompt instead. Without the key, the cache refuses commands with NOAUTH Authentication required.
Note
%LocalAppData%\locally\local-ca.pem.We can see the cache in the Locally Dashboard too:
6. Tidy up
Finally, we can tidy up. To remove the Resource Group and everything within it, including the Redis container:
$
locally run az group delete -n sample-redis --yes
There's nothing billable to clean up, since everything ran on your machine, but it's still worth checking your teardown scripts work here before you run them against Azure.
Doing this with other tooling
Whilst this guide used the Azure CLI, Azure Cache for Redis works the same way through any of the tooling that Locally supports - a Microsoft.Cache/redis resource in HashiCorp Terraform or OpenTofu, Pulumi, Bicep or an ARM Template all provision against Locally in the same way, with only the location changed.
The same goes for your application: any Redis client that supports TLS can connect using the hostName, sslPort and access key above. Just take the host and port from your tooling's outputs rather than assuming port 6380.
Next steps
To keep the access key out of your app's settings, store it in a Key Vault and read it with a Managed Identity.
Should you encounter any issues, please take a look at the troubleshooting section, reach out in our Discord or open an issue and we'll take a look.
Resource types this guide uses
These are the Azure resource types this guide creates in Locally:
- Microsoft.Cache/redis
During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in