How to get started with Managed Valkey

Last updated on: October 30, 2026

Managed Valkey runs Valkey™*, an open-source key/value data store forked from Redis. Valkey keeps its data in memory, and applications use it as a cache, a message queue or a primary database.

This guide walks you through creating a Managed Valkey service in the Control Panel or with the UpCloud API, connecting to it with valkey-cli, and using it from a Python application.

Before you start

For the API steps, you need an API token. To create one, see How to get started using the UpCloud API.

For plans, see Managed Valkey configurations. For prices, see the pricing page.

Choose your options

Before you create the Managed Valkey service, decide on these options. They set where the service runs, what it costs and who can connect to it. The steps for setting them in the Control Panel or with the API come after, in Create the Managed Valkey service.

Two of the options can't be undone: the hostname prefix can't be changed, and once the service is attached to an SDN Private Network, it can't go back to the Utility network.

Location

Create the Managed Valkey service close to the clients that will use it. If they're Cloud Servers, put the service in their location so that they can connect privately. A server in another location can't reach the service over the Utility network, even with its Utility network address in the allowed IP list, so it has to use the public hostnames instead. For the list of locations, see Managed Valkey availability.

Plan and nodes

The plan sets how many CPU cores and how much memory each node gets. Because Valkey keeps its data in memory, the memory also caps how much you can store, so leave some headroom when you choose a plan: Valkey's limit is lower than the plan's memory, and its own overhead counts towards it. When the limit is reached, the Managed Valkey service refuses new writes until you delete some data or resize to a bigger plan. If you use the service as a cache, you can let Valkey remove old keys to make room instead, as described in How to configure Managed Valkey as a cache. For every plan, see Managed Valkey configurations.

The number of nodes, from 1 to 3, decides whether the service has standby nodes:

With 1 node, the service has no standby node.
With 2 nodes, the service has a standby node for automatic failover.
With 3 nodes, the service has a second standby node.

The smallest plan, with 1 core and 1 GiB of memory, comes with a single node only. For how failover works, see Managed Valkey High availability.

Connection access

The private connection decides which private network your Cloud Servers use to reach the Managed Valkey service:

The Utility network is the default. Servers in the same location can connect over their Utility network interface, with nothing else to set up.
An SDN Private Network can be attached instead, and then only servers on that network can connect privately. The network must be attached to an SDN Router: see How to connect private networks using SDN Router.

Make this choice when you create the service. You can attach a network later, but once the service is on an SDN Private Network, it can't switch back to the Utility network, even if you detach the network.

The public connection is off by default, and while it's off, the public hostnames don't accept connections from any address. Turn it on when you want to connect over the public internet through the public hostnames, from the addresses in the allowed IP list.

Allowed IP access

Two settings decide which addresses can connect:

Automatic access from Utility network servers is on by default and lets every Cloud Server in the same location connect over the Utility network. To allow only some of them, turn it off and add their Utility network addresses to the allowed IP list.
The allowed IP list holds IPv4 addresses in CIDR notation, for example 203.0.113.10/32. It controls connections through the public hostnames, and also Utility network connections while automatic access is off. 0.0.0.0/0 allows every IP address, so with the public connection on, anyone on the internet who has the password can connect.

With an empty list, nobody can connect through the public hostnames. Servers on an attached SDN Private Network don't need to be in the list.

Maintenance schedule

Choose the day and the start time (UTC) for maintenance updates. Updates are installed during a four-hour period that starts at that time. During maintenance, the Managed Valkey service switches between nodes, which can cause a short interruption. The hostnames stay the same, but the IP addresses behind them change, so always connect by hostname. See Managed Valkey Maintenance.

Termination protection

Termination protection is off by default. Turn it on for a Managed Valkey service you can't afford to lose by accident: while it's on, the service can't be deleted or shut down until you turn protection off again.

Service name and hostname prefix

The service name is just for you, and you can change it later. The hostname prefix becomes the first part of the service's hostnames. It must be unique, start with a letter and contain only lowercase letters, numbers and dashes, and you can't change it later.

Create the Managed Valkey service

In the Control Panel, go to Databases and click Create Managed Database.
Under Location, select the location.
Under Database, select Valkey.
Under Plan, select a plan, and under Nodes, select the number of nodes. The plan list shows the monthly price of one node.
Under Connection access, turn on Public connection if you need it. For the private connection, keep Utility network, or click Attach private network, select the network under Network and click Attach.
Under Allowed IP access, keep Automatic access from Utility network servers on, or turn it off. The switch is shown only while the service uses the Utility network. Add addresses to IPv4 CIDR addresses: Servers IP picks addresses from your Cloud Servers, and Add my IP adds the address you're browsing from. Allow access from all IPs sets the list to 0.0.0.0/0.
With the defaults, Cloud Servers in the same location can connect over the Utility network, and nothing can connect over the public internet.
Set the Maintenance schedule, and turn on Termination protection if you want it.
Enter a Service name and a Hostname prefix, check the total in the Summary, then click Create Database.

The service's page opens, and the service is ready to use once its status changes to Started.

This request sets every option described above. Replace the values with your own:

POST /1.3/database

{
  "title": "<service-name>",
  "hostname_prefix": "<hostname-prefix>",
  "type": "valkey",
  "plan": "2x2xCPU-4GB",
  "zone": "de-fra1",
  "properties": {
    "valkey_version": "9.1",
    "public_access": false,
    "automatic_utility_network_ip_filter": true,
    "ip_filter": []
  },
  "maintenance": {
    "dow": "sunday",
    "time": "05:00:00"
  },
  "termination_protection": false
}

title: the service name.
hostname_prefix: the hostname prefix.
plan: the number of nodes and each node's CPU cores and memory. 2x2xCPU-4GB is 2 nodes with 2 CPU cores and 4 GiB of memory each. GET /1.3/database/service-types/valkey lists the plans in service_plans.
zone: the location.
valkey_version: the Valkey version. Set it to 9.1: without it, the service gets Valkey 8.1.
public_access: the public connection, true for on.
automatic_utility_network_ip_filter: automatic access from Utility network servers, true for on.
ip_filter: the allowed IP list, for example ["203.0.113.10/32"].
maintenance: the maintenance day (dow) and start time in UTC. Without it, the service gets a maintenance schedule automatically.
termination_protection: termination protection, true for on.

To connect the service to an SDN Private Network instead of the Utility network, add networks to the request. For example, a 1-node service on an SDN Private Network:

{
  "title": "<service-name>",
  "hostname_prefix": "<hostname-prefix>",
  "type": "valkey",
  "plan": "1x2xCPU-4GB",
  "zone": "de-fra1",
  "properties": {
    "valkey_version": "9.1"
  },
  "networks": [
    {
      "name": "<attachment-name>",
      "type": "private",
      "family": "IPv4",
      "uuid": "<network-uuid>"
    }
  ]
}

The network must be attached to an SDN Router: see How to connect private networks using SDN Router. If it isn't, the API refuses the request with Network '<network-uuid>' should be attached to a router.

The response includes the service's UUID in uuid. Use it to check on the service: it's ready once GET /1.3/database/<service-uuid> returns "state": "running".

Connect to the Managed Valkey service

To try out the connection, you need a computer with valkey-cli. How it connects depends on where it is:

A Cloud Server in the same location as the service can connect privately, without going over the public internet.
Any other computer, such as your own, connects over the public internet through the public hostnames. Turn on public connection and add the computer's public address to the allowed IP list first.

Find the connection details

Go to Databases and open the Managed Valkey service. The Overview tab shows:

Connection: the connection string, host and port. Private has the details for private connections, and Public for connections over the public internet. While public connection is off, Public shows only the switch that turns it on.
Read-only replicas: the same details for the replica hostname, on services with more than one node.
Auth: the username, default, and the password. Click Show to see the password.

Connection section of the service's Overview tab

GET /1.3/database/<service-uuid>

service_uri is the connection string, in the form rediss://default:<password>@<hostname>:<port>.
service_uri_params has the same details as separate fields: host, port, user and password.
components lists every hostname of the service, with its usage (primary or replica) and route (dynamic for private access, public for public access).

All of the service's hostnames end in .db.upclouddatabases.com:

<hostname-prefix>-<id> points to the primary node. Use it for reads and writes.
replica-<hostname-prefix>-<id> points to the standby nodes, on services with more than one node. It's handy for reads that you want to keep off the primary, but it's read-only: writes through it fail with READONLY You can't write against a read only replica.
public-<hostname-prefix>-<id> and public-replica-<hostname-prefix>-<id> are the same two over the public internet. The connection details show them only while public connection is on, and they accept connections only from addresses in the allowed IP list.

The private hostnames work from servers in the same location over the Utility network, and from servers on the SDN Private Network attached to the service.

Connect with valkey-cli

Install valkey-cli on the computer you'll connect from. On Ubuntu 26.04:

sudo apt update
sudo apt install valkey-tools

For other systems, see Valkey downloads. Make sure your build supports TLS: valkey-cli --help should list --tls.

The commands below use the connection string of the Managed Valkey service. In the Control Panel, the copy icon next to Connection string copies it to your clipboard, including the password. Which tab to copy it from depends on where you run the commands:

On a Cloud Server in the same location as the service, use the Private tab.
On any other computer, use the Public tab.

With the API, service_uri has the connection string with the private hostname.

By default, the service accepts only TLS connections. You don't need to do anything extra for that: the rediss:// scheme in the connection string turns TLS on, and because the service's certificate is signed by a public certificate authority, there's no CA certificate to download.

Check that you can reach the service with a PING:

valkey-cli -u 'rediss://default:<password>@<hostname>:<port>' PING

Output
Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.
PONG

Now store a value and read it back:

valkey-cli -u 'rediss://default:<password>@<hostname>:<port>' SET greeting "Hello from Managed Valkey"
valkey-cli -u 'rediss://default:<password>@<hostname>:<port>' GET greeting

Output
Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.
OK
Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.
"Hello from Managed Valkey"

The warning appears whenever the password is part of the command. To keep it out of the command, use --askpass instead, and valkey-cli reads the password from standard input:

valkey-cli --tls -h <hostname> -p <port> --user default --askpass PING

Connect from an application

Applications connect the same way, with a Valkey client library and the same connection string. This example uses valkey-py, the Python client from the Valkey project.

Install it in a virtual environment. On Ubuntu 26.04:

sudo apt install python3-venv
python3 -m venv venv
source venv/bin/activate
pip install valkey

Save this short program as app.py. It reads the connection string from an environment variable, stores a value and prints it back:

import os

import valkey

client = valkey.from_url(os.environ["VALKEY_URI"], decode_responses=True)

client.set("greeting", "Hello from Python")
print(client.get("greeting"))

Run it with your connection string in VALKEY_URI:

export VALKEY_URI='rediss://default:<password>@<hostname>:<port>'
python app.py

Output
Hello from Python

This example connects as default, which has full access to every key. To give each application its own user with only the access it needs, see How to restrict user access in Managed Valkey.

Delete the Managed Valkey service

Go to Databases and open the service.
Click Shut down, then click Shut down in the dialog. The status changes to Stopped. While the service is started, Delete isn't available.
Open the menu next to Start and select Delete.
Click Delete to confirm.

The service's menu with Delete, after the service is stopped

The Control Panel returns to the list of databases.

If termination protection is on, the Shut down dialog tells you so and won't let you continue. Cancel it, turn off the Termination protection switch on the service's Overview tab, and start again.

DELETE /1.3/database/<service-uuid>

The API answers with 204 No Content. While the service is being removed, GET /1.3/database/<service-uuid> can still return it, with a state such as cleanup-network, and once it's gone, the request returns 404.

If termination protection is on, the API refuses the request with Service cannot be deleted, termination protection is enabled. Turn protection off first:

PATCH /1.3/database/<service-uuid>

{
  "termination_protection": false
}

Troubleshooting

I/O error and Error: Server closed the connection
The client connected without TLS. Use a connection string that starts with rediss://, or add --tls to the valkey-cli command.
NOAUTH Authentication required. on its own
The client didn't send a password. Use the full connection string, or add --user default --askpass.
AUTH failed: WRONGPASS invalid username-password pair or user is disabled.
The password is wrong. valkey-cli also prints NOAUTH Authentication required. in this case. Copy the password again from the connection details.
OOM command not allowed when used memory > 'maxmemory'.
The memory of the Managed Valkey service is full. Reads still work, but writes fail until you delete data you no longer need or resize to a bigger plan on the service's Settings tab. Your data is kept when you resize. If the service is a cache, set an eviction policy so that Valkey removes old keys instead, as described in How to configure Managed Valkey as a cache.
READONLY You can't write against a read only replica.
The client connected through a replica- hostname. Send writes to the primary hostname.
Connections through a public hostname time out
Either public connection is off, or the address you're connecting from isn't in the allowed IP list. Turn public connection on and add the address to the list, or connect from a server over a private network.
Connections from a new server in the same location time out
A Cloud Server created after the service can take a while to get access over the Utility network. To let it connect straight away, add the server's Utility network address to the allowed IP list, for example 10.4.15.173/32. Use the Utility network address, not the public one, because that's the address the server connects from.
Connections from a server on the SDN Private Network time out
A server that joined the network before the service did only gets the route to the service when it renews its DHCP lease. Find the server's interface on the SDN Private Network with ip -br addr, then renew the lease. On Ubuntu:
```
sudo networkctl renew <interface>
```

Next steps

How to restrict user access in Managed Valkey shows how to create users that can use only the keys and commands they need.
How to configure Managed Valkey as a cache explains how to set an eviction policy and cache data from an application.
How to migrate Redis or Valkey to Managed Valkey shows how to copy the data from a Redis or Valkey server you run yourself.
Connecting to Managed Valkey describes the private and public connection options.
Managed Valkey High availability describes how primary and standby nodes work.
Customisable Managed Valkey properties lists the settings you can change with the API.

* Valkey and the Valkey logo are trademarks of LF Projects, LLC. Any rights therein are reserved to LF Projects, LLC. Any use by UpCloud is for referential purposes only and does not indicate any sponsorship, endorsement or affiliation between Valkey and UpCloud. Other names may be trademarks of their respective owners.

Contributed by: Samir Haliru