canonical · reneradoi · Apr 13, 2026 · Mar 16, 2026 · Mar 16, 2026 · Mar 16, 2026
diff --git a/README.md b/README.md
@@ -0,0 +1,86 @@
+## Valkey operator
+[![CharmHub Badge](https://charmhub.io/valkey/badge.svg)](https://charmhub.io/valkey)
+[![docs badge](https://app.readthedocs.com/projects/canonical-charmed-valkey/badge/?version=latest&style=plastic)](https://app.readthedocs.com/projects/canonical-charmed-valkey/builds/?version__slug=latest)
+
+Charmed Valkey is an open-source Juju charm that will automate the deployment, 
+scaling, configuration and operations of Valkey databases across clouds, virtual
+machines and bare metal, using the Juju orchestration framework.
+
+[Valkey](https://valkey.io) is a community-driven, open-source, high-performance
+key-value data store compatible with Redis® clients and ecosystem tooling.
+
+The charm can be deployed on Kubernetes and VM clouds and aims to simplify Valkey
+operations from [Day 0 to Day 2](https://codilime.com/blog/day-0-day-1-day-2-the-software-lifecycle-in-the-cloud-age/), 
+offering secure defaults integration interfaces, and lifecycle automation.
+
+## Basic usage
+
+Bootstrap a [MicroK8s controller](https://documentation.ubuntu.com/juju/3.6/tutorial/#set-up-a-juju-controller)
+and create a new Juju model:
+
+```shell
+juju add-model sample-model
+```
+
+To deploy a single unit of Valkey, run the following command:
+
+```shell
+juju deploy valkey --channel 9/edge --trust
+```
+
+To deploy Valkey with multiple units, specify the number of desired units with the `-n` option:
+
+```shell
+juju deploy valkey -n 3 --channel 9/edge --trust
+```
+
+Valkey can be scaled out using the `juju add-unit` command:
+
+```shell
+juju add-unit valkey -n <num_of_desired_units>
+```
+
+For example, to scale a deployment with three Valkey units to five, run:
+
+```shell
+juju add-unit valkey -n 2
+```
+
+Even when scaling multiple units at the same time, the charmed operator uses a rolling restart 
+sequence to make sure the cluster stays available and healthy during the operation.
+
+## Download details
+
+Charmed Valkey is shipped in the track `9/edge`: [Valkey 9/edge](https://charmhub.io/valkey?channel=9/edge)
+
+It is based on the following platform:
+- Noble (Ubuntu 24.04)
+- Supported architectures: `amd64`.
+
+## Documentation
+
+The [charmed Valkey documentation](https://canonical-charmed-valkey.readthedocs-hosted.com) provides a 
+tutorial for basic usage, multiple how-to guides about operational topics, and detailed 
+information about supported interfaces and integrations.
+
+## Community and support
+
+The charmed Valkey operator is an open-source project that welcomes community contributions, suggestions,
+fixes and constructive feedback.
+
+- Report [issues](https://github.com/canonical/valkey-operator/issues)
+- [Contact us on Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com)
+- Explore [Canonical Data & AI solutions](https://canonical.com/data)
+
+Charmed Valkey is covered by the [Ubuntu Code of
+Conduct](https://ubuntu.com/community/ethos/code-of-conduct).
+
+## Contributing
+
+Please see the [Juju docs](https://documentation.ubuntu.com/juju/3.6/howto/manage-applications/) for 
+guidelines and best practices, and the [contribution guide](CONTRIBUTING.md) for developer guidance.
+
+## License and copyright
+
+Charmed Valkey is free software, distributed under the Apache Software License, version 2.0. 
+See [LICENSE](LICENSE) for more information.
diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
@@ -70,3 +70,4 @@ docstrings?
 Makefile
 retrigger(ing)?
 Valkey
+failover
diff --git a/docs/how-to/deploy.md b/docs/how-to/deploy.md
@@ -0,0 +1,28 @@
+# How to deploy
+
+This guide provides deployment instructions for Charmed Valkey. It supports both 
+Kubernetes and VM clouds and can be deployed seamless on both substrates.
+
+## Prerequisites
+
+The basic requirements for deploying a charm are the [**Juju client**](https://documentation.ubuntu.com/juju/3.6/) 
+and a [**cloud**](https://juju.is/docs/juju/cloud).
+
+## Setup
+
+First, [bootstrap](https://juju.is/docs/juju/juju-bootstrap) the cloud controller
+and create a [model](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/model/):
+
+```shell
+juju bootstrap <cloud name> <controller name>
+juju add-model <model name>
+```
+
+Then, use the [`juju deploy`](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/juju-cli/list-of-juju-cli-commands/deploy/) command:
+
+```shell
+juju deploy valkey --channel 9/edge -n <number_of_replicas> --trust
+```
+
+If you are not sure where to start or would like a more guided walk through for
+setting up your environment, see the {ref}`tutorial`.
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -0,0 +1,13 @@
+# How-to guides
+
+These guides accompany you through the operations lifecycle of Charmed Valkey.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Deploy <deploy>
+Scale horizontally <scale-horizontally>
+Manage passwords <manage-passwords>
+TLS encryption <tls>
+```
diff --git a/docs/how-to/manage-passwords.md b/docs/how-to/manage-passwords.md
@@ -0,0 +1,138 @@
+# How to manage passwords
+
+This guide provides instructions for creating, updating, and otherwise managing passwords.
+
+To read or write data in Valkey, we need to authenticate ourselves.
+
+For this guide, we will use Charmed {spellexception}`Valkey's` internal admin user
+`charmed-operator`. This user is only for internal use, and it is created automatically
+by Charmed Valkey.
+
+We will go through setting a user-defined password for this admin user and configuring
+Valkey. 
+
+## Auto-generated credentials
+
+For security purposes, Charmed Valkey automatically generates users and passwords 
+for its operations and internal administration tasks. These credentials are stored
+in a Juju secret owned by the charm. Inspect the secret:
+
+```shell
+juju show-secret valkey-peers.valkey.app.internal_users_secret --reveal
+```
+
+```{caution}
+This secret is only for internal use. It must not be updated by users.
+```
+
+To override the auto-generated passwords for the internal users, follow the instructions
+of the next section.
+
+## Configure a user-provided password
+
+First, create a secret in `Juju` containing your password:
+
+```shell
+juju add-secret passwords charmed-operator=<NEW_PASSWORD>
+```
+
+You will get the `secret` ID as a response:
+
+```text
+secret:d6s4mr7mp25c765ucep0
+```
+
+Make note of the string following `secret:`.
+
+Grant the secret to Charmed Valkey:
+
+```shell
+juju grant-secret passwords valkey
+```
+
+Configure the secret's URI as `system-users` credentials to Charmed Valkey:
+
+```shell
+juju config valkey system-users=secret:d6s4mr7mp25c765ucep0
+```
+
+Charmed Valkey will now apply the new password to its internal admin user. You can
+check the progress by running `juju status`. After a few moments, the deployment will settle:
+
+```text
+Model     Controller      Cloud/Region        Version  SLA          Timestamp
+tutorial  k8s-controller  microk8s/localhost  3.6.14   unsupported  19:28:26+01:00
+
+App                       Version  Status  Scale  Charm                     Channel   Rev  Address         Exposed  Message
+self-signed-certificates           active      1  self-signed-certificates  1/stable  586  10.152.183.111  no       
+valkey                             active      3  valkey                    9/edge     11  10.152.183.123  no       
+
+Unit                         Workload  Agent  Address      Ports  Message
+self-signed-certificates/0*  active    idle   10.1.44.89          
+valkey/0*                    active    idle   10.1.44.126         
+valkey/1                     active    idle   10.1.44.117         
+valkey/2                     active    idle   10.1.44.127         
+```
+
+Now you can use the password to access Valkey. Select the IP address for one of the units to connect to:
+
+```shell
+valkey-cli -h 10.1.44.126 -p 6379
+```
+
+Authenticate with the username and password you just configured:
+
+```text
+10.1.44.126:6379> AUTH charmed-operator <NEW_PASSWORD>
+```
+
+Check the current health of the server with this command:
+
+```text
+10.1.44.126:6379> ping
+```
+
+## Update the password
+
+To update your user-configured password, simply update the value of the secret. Here's an example:
+
+```shell
+juju update-secret passwords charmed-operator=<MORE_SECURE_PASSWORD>
+```
+
+After running this command, Charmed Valkey will immediately update the password.
+Once the deployment has settled to `active`/`idle` state again, you can no longer use
+the old password to access Valkey. Instead, you will receive an error similar to this:
+
+```text
+(error) WRONGPASS invalid username-password pair or user is disabled.
+```
+
+Instead, use your updated password to authenticate:
+
+```text
+10.1.44.126:6379> AUTH charmed-operator moresecurepassword
+```
+
+## Handle multiple passwords
+
+Charmed Valkey maintains multiple internal users with different permissions for
+different scopes:
+
+* `charmed-operator`: the user that manages the database instances
+* `charmed-replication`: the user performs replication between primary and replica instances of Valkey
+* `charmed-sentinel-operator`: the user that manages Sentinel for Valkey
+* `charmed-sentinel-peers`: the user for communication between Sentinel instances
+* `charmed-sentinel-valkey`: the user that Sentinel uses to connect to Valkey
+* `charmed-stats`: the user for monitoring and observability
+
+It is possible to manage the passwords for all of above's users with a Juju secret, 
+or just for some of them.
+
+To set the password for the `charmed-operator` and `charmed-sentinel-operator` users, 
+but keeping the automatically generated passwords for all other users, run the following
+command:
+
+```shell
+juju update-secret passwords charmed-operator=<MORE_SECURE_PASSWORD> charmed-sentinel-operator=<SENTINEL_PASSWORD>
+```
diff --git a/docs/how-to/scale-horizontally.md b/docs/how-to/scale-horizontally.md
@@ -0,0 +1,69 @@
+# How to scale horizontally
+
+Horizontal scaling of a Valkey deployment is done by adding and removing [Juju units](https://juju.is/docs/juju/unit). 
+
+## Add a unit
+
+To add additional units to your deployed Valkey application, run the following command:
+
+```shell
+juju add-unit valkey -n 1
+```
+
+Where `-n 1` specifies the number of units to add.
+
+You can now watch the new unit join the deployment with `watch juju status`.
+It usually takes a few minutes for a unit to be added to an existing deployment.
+
+```text
+Model     Controller      Cloud/Region        Version  SLA          Timestamp
+tutorial  k8s-controller  microk8s/localhost  3.6.14   unsupported  19:21:12+01:00
+
+App                       Version  Status  Scale  Charm                     Channel   Rev  Address         Exposed  Message
+self-signed-certificates           active      1  self-signed-certificates  1/stable  586  10.152.183.111  no       
+valkey                             active      4  valkey                    9/edge     11  10.152.183.123  no       
+
+Unit                         Workload  Agent  Address      Ports  Message
+self-signed-certificates/0*  active    idle   10.1.44.89          
+valkey/0*                    active    idle   10.1.44.126         
+valkey/1                     active    idle   10.1.44.117         
+valkey/2                     active    idle   10.1.44.127         
+valkey/3                     active    idle   10.1.44.68          
+```
+
+### Remove units
+
+Removing a unit from the application scales down the application. If you currently have
+four units, then only one is the primary and three are replicas. Removing a unit will reduce the
+number of replicas to two and the total number of units to three.
+
+Before scaling down, list all the units with `juju status`:
+
+* `valkey/0`
+* `valkey/1`
+* `valkey/2`
+* `valkey/3`
+
+To scale the application down to three units, run:
+
+```shell
+juju remove-unit valkey --num-units 1
+```
+
+Safely removing the unit will take a few moments. You’ll know that the unit was
+successfully removed when `juju status` reports all units `active`/`idle` again:
+
+```text
+Model     Controller      Cloud/Region        Version  SLA          Timestamp
+tutorial  k8s-controller  microk8s/localhost  3.6.14   unsupported  19:23:44+01:00
+
+App                       Version  Status  Scale  Charm                     Channel   Rev  Address         Exposed  Message
+self-signed-certificates           active      1  self-signed-certificates  1/stable  586  10.152.183.111  no       
+valkey                             active      3  valkey                    9/edge     11  10.152.183.123  no       
+
+Unit                         Workload  Agent  Address      Ports  Message
+self-signed-certificates/0*  active    idle   10.1.44.89          
+valkey/0*                    active    idle   10.1.44.126         
+valkey/1                     active    idle   10.1.44.117         
+valkey/2                     active    idle   10.1.44.127         
+```