[DPE-9311] Initial user documentation

README.md

@@ -0,0 +1,86 @@
+## Valkey operator
+[![CharmHub Badge](https://charmhub.io/valkey/badge.svg)](https://charmhub.io/valkey)
+[![docs badge](https://canonical-charmed-valkey.readthedocs-hosted.com/en/latest/)](https://canonical-charmed-valkey.readthedocs-hosted.com/)
+
+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, 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.

docs/.custom_wordlist.txt

@@ -70,3 +70,4 @@ docstrings?
 Makefile
 retrigger(ing)?
 Valkey
+failover

docs/how-to/deploy.md

@@ -0,0 +1,23 @@
+# How to deploy
+
+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).
+
+## Quickstart
+
+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`.

docs/how-to/index.md

@@ -0,0 +1,11 @@
+# How-to guides
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Deploy <deploy>
+Scale horizontally <scale-horizontally>
+Manage passwords <manage-passwords>
+TLS encryption <tls/index>
+```

docs/how-to/manage-passwords.md

@@ -0,0 +1,115 @@
+# How to manage passwords
+
+In order 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. 
+
+## Configure a user-provided password
+
+First, create a secret in `Juju` containing your password:
+
+```text
+juju add-secret passwords charmed-operator=changeme
+```
+
+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:
+
+```text
+juju grant-secret passwords valkey
+```
+
+Configure the secret's URI as `system-users` credentials to Charmed Valkey:
+
+```text
+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
+and check the current health with this command:
+
+```text
+$ valkey-cli -h 10.1.44.126 -p 6379
+10.1.44.126:6379> AUTH charmed-operator changeme
+OK
+10.1.44.126:6379> ping
+PONG
+```
+
+## Update the password
+
+To update your user-configured password, simply update the value of the secret. Here's an example:
+
+```text
+juju update-secret passwords charmed-operator=moresecurepassword
+```
+
+After running this command, Charmed Valkey will immediately update the password.
+After the deployment has settled again, you can no longer use the old password to
+access Valkey. Instead, you will receive an error similar to this:
+
+```text
+$ valkey-cli -h 10.1.44.126 -p 6379
+10.1.44.126:6379> AUTH charmed-operator changeme
+(error) WRONGPASS invalid username-password pair or user is disabled.
+```
+
+Instead, use your updated password:
+
+```text
+$ valkey-cli -h 10.1.44.126 -p 6379
+10.1.44.126:6379> AUTH charmed-operator moresecurepassword
+OK
+```
+
+## 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:
+
+```text
+juju update-secret passwords charmed-operator=moresecurepassword charmed-sentinel-operator=sentinelpassword
+```

docs/how-to/scale-horizontally.md

@@ -0,0 +1,67 @@
+# How to scale horizontally
+
+Adding and removing units from a Valkey deployment is done by scaling [Juju units](https://juju.is/docs/juju/unit). 
+
+## Add a unit
+You can add additional units to your deployed Valkey application with the following command:
+
+```text
+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 replicas. If you currently have
+three units, one is the primary and two are replicas. Removing a unit will reduce the
+number of replicas to one.
+
+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:
+
+```text
+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:
+
+```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         
+```

docs/how-to/tls/disable-tls.md

@@ -0,0 +1,68 @@
+# How to disable TLS
+
+To follow this guide, you need to have a running Charmed Valkey deployment with TLS
+enabled. See [How to enable TLS](#enable-tls) for more information.
+
+In general, to disable encryption with TLS, remove the relation between Valkey and 
+the TLS provider on the client-certificates endpoint:
+
+```text
+Model     Controller      Cloud/Region        Version  SLA          Timestamp
+tutorial  k8s-controller  microk8s/localhost  3.6.14   unsupported  19:06:13+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         
+
+Integration provider                   Requirer                    Interface         Type     Message
+self-signed-certificates:certificates  valkey:client-certificates  tls-certificates  regular  
+valkey:status-peers                    valkey:status-peers         status_peers      peer     
+valkey:valkey-peers                    valkey:valkey-peers         valkey_peers      peer     
+```
+
+To disable the client-to-server communication, run:
+
+```text
+juju remove-relation valkey:client-certificates self-signed-certificates
+```
+
+After some time, you'll see that the relation between `self-signed-certificates` and Valkey
+has been removed:
+
+```text
+Model     Controller      Cloud/Region        Version  SLA          Timestamp
+tutorial  k8s-controller  microk8s/localhost  3.6.14   unsupported  19:08:08+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         
+
+Integration provider  Requirer             Interface     Type  Message
+valkey:status-peers   valkey:status-peers  status_peers  peer  
+valkey:valkey-peers   valkey:valkey-peers  valkey_peers  peer  
+```
+
+You have successfully disabled encryption with TLS for Valkey. You can verify that
+the database is running without encryption by checking the `valkey-cli` command
+without the `tls` directive:
+
+```text
+$ valkey-cli -h 10.1.44.126 -p 6379
+10.1.44.126:6379> ping
+(error) NOAUTH Authentication required.
+```
+
+Notice that the database is running without encryption for client connections only.
+For internal peer-to-peer communication, Charmed Valkey always uses TLS by default.