Skip to content

Commit 24c7e86

Browse files
KyrremannmortenljReasonable-Solutions
authored
Docs for valkey (#724)
* valkey: kopi av Redis Co-authored-by: Morten Lied Johansen <[email protected]> Co-authored-by: Carl Hedgren <[email protected]> * bump deps * Fix: Fix Makefile * add deprecation notice --------- Co-authored-by: Morten Lied Johansen <[email protected]> Co-authored-by: Carl Hedgren <[email protected]>
1 parent 7421ede commit 24c7e86

File tree

12 files changed

+328
-23
lines changed

12 files changed

+328
-23
lines changed

‎Makefile

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,4 @@ install:
77
poetry install
88

99
local:
10-
TENANT=$(tenant) poetry run mkdocs serve
10+
poetry run mkdocs serve

‎docs/observability/how-to/auto-instrumentation.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ tags: [how-to, tracing, observability]
77

88
This guide will explain how to get started with auto-instrumentation your applications with OpenTelemetry data for [Tracing](../tracing/README.md), [Metrics](../metrics/README.md) and [Logs](../logging/README.md) using the OpenTelemetry Agent.
99

10-
The main benefit of auto-instrumentation is that is requires little to no effort on the part of the team developing the application while providing insight into popular libraries, frameworks and external services such as PostgreSQL, Redis, Kafka and HTTP clients.
10+
The main benefit of auto-instrumentation is that is requires little to no effort on the part of the team developing the application while providing insight into popular libraries, frameworks and external services such as PostgreSQL, Redis, Valkey, Kafka and HTTP clients.
1111

1212
Auto-instrumentation is a preferred way to get started with tracing in NAIS, and can also be used for metrics and logs collection.This type of instrumentation is available for Java, Node.js and Python applications, but can also be used for other in `sdk` mode where it will only set up the OpenTelemetry configuration.
1313

‎docs/observability/tracing/README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ NAIS does not collect application trace data automatically, but it provides the
4646

4747
The preferred way to get started with tracing is to enable auto-instrumentation for your application. This will automatically collect traces and send them to the correct place using the OpenTelemetry Agent.
4848

49-
This is the easiest way to get started with tracing, as it requires little to no effort on the part of the team developing the application and provides instrumentation for popular libraries, frameworks and external services such as PostgreSQL, Redis, Kafka and HTTP clients.
49+
This is the easiest way to get started with tracing, as it requires little to no effort on the part of the team developing the application and provides instrumentation for popular libraries, frameworks and external services such as PostgreSQL, Redis, Valkey, Kafka and HTTP clients.
5050

5151
[:dart: Get started with auto-instrumentation](../how-to/auto-instrumentation.md)
5252

@@ -74,9 +74,9 @@ While tracing is only concerned about request/response metadata there are some e
7474
Bellow is a list of known fields you should check for your application.
7575

7676
| Trace type | Known fields |
77-
| ---------- | --------------------------------------------------- |
77+
|------------|-----------------------------------------------------|
7878
| HTTP | `url.path`, `target.path`, `route.path`, `url.full` |
79-
| Redis | `db.statement` |
79+
| Valkey | `db.statement` |
8080
| Postgres | `db.statement` |
8181
| Kafka | `messaging.kafka.message.key` |
8282

‎docs/persistence/README.md

+13-13
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ Choose wisely.
3333

3434
```mermaid
3535
graph TD
36-
F[I need caching!] --> REDIS[Redis]
36+
F[I need caching!] --> VALKEY[Valkey]
3737
A[I got data!] --> B[Is it structured?]
3838
B --> |Yes| C[Is it events?]
3939
B --> |No| D[Is it files?]
@@ -44,7 +44,7 @@ graph TD
4444
E --> |Yes| GBQ[BigQuery]
4545
E --> |No| GCSQL[Cloud SQL]
4646
47-
click REDIS "#redis"
47+
click VALKEY "#valkey"
4848
click GBQ "#bigquery"
4949
click GCS "#cloud-storage-buckets"
5050
click GCSQL "#cloud-sql"
@@ -56,14 +56,14 @@ graph TD
5656

5757
Below is a list of the different storage options available to you.
5858

59-
| Name | Type | Availability | Backup |
60-
|-----------------------------------------|-------------|:------------:|:------:|
61-
| [Kafka](#kafka) | Streaming | All | Yes* |
62-
| [Cloud Storage](#cloud-storage-buckets) | Object | GCP | Yes* |
63-
| [Cloud SQL](#cloud-sql) | Relational | GCP | Yes |
64-
| [BigQuery](#bigquery) | Relational | GCP | Yes* |
65-
| [OpenSearch](#opensearch) | Document | GCP | Yes |
66-
| [Redis](#redis) | Key/Value | GCP | Yes |
59+
| Name | Type | Availability | Backup |
60+
|-----------------------------------------|------------|:------------:|:------:|
61+
| [Kafka](#kafka) | Streaming | All | Yes* |
62+
| [Cloud Storage](#cloud-storage-buckets) | Object | GCP | Yes* |
63+
| [Cloud SQL](#cloud-sql) | Relational | GCP | Yes |
64+
| [BigQuery](#bigquery) | Relational | GCP | Yes* |
65+
| [OpenSearch](#opensearch) | Document | GCP | Yes |
66+
| [Valkey](#valkey) | Key/Value | GCP | Yes |
6767

6868
\* Data is highly available and fault-tolerant but not backed up if deleted by
6969
mistake.
@@ -108,10 +108,10 @@ OpenSearch offers a drop-in replacement for Elasticsearch.
108108

109109
[:bulb: Learn more about OpenSearch](./opensearch/README.md)
110110

111-
## Redis
111+
## Valkey
112112

113-
Redis is a key value database that is used for storing and querying data. It is
113+
Valkey is a key value database that is used for storing and querying data. It is
114114
a good choice for storing data that is not relational in nature and often used
115115
for caching.
116116

117-
[:bulb: Learn more about Redis](./redis/README.md)
117+
[:bulb: Learn more about Valkey](./valkey/README.md)

‎docs/persistence/redis/README.md

+9-1
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,16 @@ tags: [persistence, explanation, redis, services]
33
---
44
# Redis
55

6-
<<gcp_only("Redis")>>
6+
!!! warning Deprecated
7+
8+
Due to licensing changes Redis is deprecated and new instances cannot be created after the 15th february 2025.
9+
10+
The replacment, Valkey is available and offers bug-for-bug api compatibility.
711

12+
See [Valkey](../valkey/README.md)
13+
14+
15+
<<gcp_only("Redis")>>
816

917
Redis is a key value database that is used for storing and querying data. It is
1018
a good choice for storing data that is not relational in nature and often used

‎docs/persistence/valkey/README.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
tags: [persistence, explanation, valkey, redis, services]
3+
---
4+
# Valkey
5+
6+
<<gcp_only("Valkey")>>
7+
8+
9+
Valkey is a key value database that is used for storing and querying data.
10+
It is a good choice for storing data that is not relational in nature and often used for caching.
11+
12+
## Related pages
13+
14+
:dart: [Create Valkey via Application](how-to/create-application.md)
15+
16+
:dart: [Create Valkey as a standalone instance](how-to/create-explicit.md).
17+
18+
:dart: [Delete Valkey](how-to/delete.md)

‎docs/persistence/valkey/how-to/create-application.md

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
tags: [how-to, valkey, redis]
3+
---
4+
5+
# Create Valkey via Application
6+
7+
You can create many Valkey instances for your `Application`.
8+
9+
## Prerequisites
10+
- [Member of a NAIS team](../../../explanations/team.md)
11+
12+
!!! warning
13+
14+
It is not possible to share Valkey instances between teams.
15+
16+
## Enable Valkey in your [manifest][app-spec-valkey]
17+
18+
!!! note ".nais/app.yaml"
19+
```yaml
20+
spec:
21+
valkey:
22+
- instance: sessions
23+
access: readwrite
24+
- instance: lookup
25+
access: read
26+
```
27+
28+
The above snippet will allow your application to use the `sessions` Valkey instance, and provide the application with credentials for a read/write user.
29+
In addition, the application will get credentials for a read-only user for the `lookup` instance. See the [manifest reference][app-spec-valkey] for other options for `access`.
30+
31+
The default Valkey created by NAIS looks like this:
32+
33+
```yaml
34+
apiVersion: aiven.io/v1alpha1
35+
kind: Valkey
36+
metadata:
37+
labels:
38+
app: valkey-tester
39+
team: myteam
40+
name: valkey-myteam-sessions
41+
namespace: myteam
42+
spec:
43+
plan: startup-4
44+
project: nav-dev
45+
```
46+
47+
If all you need is a Valkey instance for one application using just the default settings, this is all you need.
48+
If you want to share a Valkey instance across applications, or want to change configuration away from the defaults, please read the [section on explicitly creating Valkey instances](create-explicit.md).
49+
50+
For each Valkey instance, your application will receive three environment variables.
51+
The environment variables use a fixed prefix, and the instance name uppercased as a suffix.
52+
53+
| Key | Value |
54+
|---------------------------------|--------------------------------------|
55+
| `VALKEY_URI_<InstanceName>` | The URI for the instance |
56+
| `VALKEY_HOST_<InstanceName>` | The host for the instance |
57+
| `VALKEY_PORT_<InstanceName>` | The port for the instance |
58+
| `VALKEY_USERNAME_<InstanceName>` | The username to use when connecting. |
59+
| `VALKEY_PASSWORD_<InstanceName>` | The password to use when connecting. |
60+
61+
[app-spec-valkey]: ../../../workloads/application/reference/application-spec.md#valkey

‎docs/persistence/valkey/how-to/create-explicit.md

+127
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
tags: [how-to, valkey, redis]
3+
---
4+
5+
# Create a Valkey instance explicitly
6+
7+
## Prerequisites
8+
- [Member of a NAIS team](../../../explanations/team.md)
9+
10+
We recommend creating your Valkey instances in their own workflow for more control over configuration, especially if you intend for multiple applications using the same Valkey instance, or if you need to change configuration.
11+
12+
Creating a Valkey instance is done by adding a Valkey resource to your namespace with detailed configuration.
13+
Some configuration is enforced by the NAIS platform, while the rest is up to the users.
14+
15+
Earlier we talked about the "instance name".
16+
In reality, the actual name of the valkey instance will be `valkey-<team name>-<instance name>` (where `team name` is the same as the namespace your application resides in).
17+
The resource needs to have this full name in order to be accepted.
18+
19+
The default Valkey created by NAIS looks like this:
20+
21+
```yaml
22+
apiVersion: aiven.io/v1alpha1
23+
kind: Valkey
24+
metadata:
25+
labels:
26+
app: valkey-tester
27+
team: myteam
28+
name: valkey-myteam-sessions
29+
namespace: myteam
30+
spec:
31+
plan: startup-4
32+
project: nav-dev
33+
```
34+
35+
A minimal Valkey resource only requires `plan` and `project`.
36+
37+
* `project` should match your NAIS tenant (`<<tenant()>>`) and the environment you are running in (ex. `dev`, `prod`), with a dash (`-`) in between.
38+
* `plan` is the Aiven plan for your Valkey instance.
39+
See Aivens list of [possible plan values](https://aiven.io/pricing?product=valkey).
40+
The values are lowercased.
41+
Make sure you understand the differences between the plans before selecting the one you need.
42+
Examples: `startup-4`, `startup-56`, `business-4`, `premium-14`.
43+
44+
We use Aivens operator, so the Valkey resource is [documented in detail](https://aiven.github.io/aiven-operator/api-reference/valkey.html) in the Aiven documentation.
45+
You should look at the reference for any other fields that might be of interest.
46+
47+
Probably the most important value to consider is which plan to use.
48+
49+
The Startup plans are good for things like sessions or cache usage, where High Availability in case of failures is not important.
50+
Upgrades and regular maintenance is handled without noticeable downtime, by adding a new upgraded node and replicating data over to it before switching over DNS and shutting down the old node.
51+
Startup plans are backed up every 12 hours, keeping 1 backup available.
52+
53+
If you require HA, the Business plans provide for one failover node that takes over should your primary instance fail for any reason.
54+
When using business plans, a second node is always available with continuous replication, so it is able to start serving data immediately should the primary node fail.
55+
Business plans are backed up every 12 hours, keeping 3 days of backups available.
56+
57+
Once the resource is added to the cluster, some additional fields are filled in by the platform and should be left alone unless you have a good reason:
58+
59+
| field | |
60+
|-------------------------|-------------------------------------------------------------------------------------------------------|
61+
| `projectVpcId` | Ensures the instance is connected to the correct project VPC and is not available on public Internet. |
62+
| `tags` | Adds tags to the instance used for tracking billing in Aiven. |
63+
| `cloudName` | Where the Valkey instance should run. |
64+
| `terminationProtection` | Protects the instance against unintended termination. Must be set to `false` before deletion. |
65+
66+
There are some fields available that should not be used:
67+
68+
| field | |
69+
|------------------------|-------------------------------------------------------------------------------------------------|
70+
| `authSecretRef` | Reference to a secret containing an Aiven API token. Provided via other mechanisms. |
71+
| `connInfoSecretTarget` | Name of secret to put connection info in, not used as NAIS provides these via other mechanisms. |
72+
| `projectVPCRef` | Not used since we use `projectVpcId`. |
73+
| `serviceIntegrations` | Not used at this time. |
74+
75+
{% if tenant() in ("nav", "dev-nais") %}
76+
77+
### ServiceIntegration
78+
79+
A ServiceIntegration is used to integrate the Valkey instance with Prometheus.
80+
It is pretty straight forward, with little to no configuration needed.
81+
82+
Simple 5 steps procedure:
83+
84+
1. Copy the below yaml into a file (it can be the same file as your Valkey instance)
85+
2. Replace `<ENV>` with the environment you are running in (ex. `dev`, `prod`) (in field `project`)
86+
3. Replace `<MYTEAM>` with your team name (in `labels`, `namespace` and `sourceServiceName`)
87+
4. Replace `<INSTANCE>` with the last part of the name of your Valkey instance (in `name` and `sourceServiceName`)
88+
5. Replace `<ENDPONT-ID>` with the endpoint ID from the table below (in `destinationEndpointId`)
89+
6. Deploy the resource using the same pipeline as you use for your Valkey instance
90+
91+
92+
!!! note "valkey.yaml"
93+
```yaml
94+
---
95+
apiVersion: aiven.io/v1alpha1
96+
kind: ServiceIntegration
97+
metadata:
98+
labels:
99+
team: <MYTEAM>
100+
name: valkey-<MYTEAM>-<INSTANCE>
101+
namespace: <MYTEAM>
102+
spec:
103+
project: <<tenant()>>-<ENV>
104+
integrationType: prometheus
105+
destinationEndpointId: <ENDPONT-ID>
106+
sourceServiceName: valkey-<MYTEAM>-<INSTANCE>
107+
```
108+
109+
#### Prometheus Endpoint IDs
110+
111+
{% if tenant() == "nav" %}
112+
113+
| Environment | Endpoint ID |
114+
|-------------|--------------------------------------|
115+
| nav-dev | f20f5b48-18f4-4e2a-8e5f-4ab3edb19733 |
116+
| nav-prod | 76685598-1048-4f56-b34a-9769ef747a92 |
117+
118+
{% elif tenant() == "dev-nais" %}
119+
120+
| Environment | Endpoint ID |
121+
|--------------|--------------------------------------|
122+
| dev-nais-dev | cc2fd0ad-9e62-492e-b836-86aa9654fd9b |
123+
124+
{% endif %}
125+
126+
{% endif %}
127+

‎docs/persistence/valkey/how-to/delete.md

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
tags: [how-to, valkey, redis]
3+
---
4+
5+
# Delete Valkey
6+
7+
This page guides you through the steps required to delete a Valkey instance.
8+
9+
## Prerequisites
10+
11+
- [You are a member of a NAIS team](../../../explanations/team.md)
12+
- [You have set up command-line access](../../../operate/how-to/command-line-access.md)
13+
14+
## Steps
15+
16+
Before you delete a Valkey instance, ensure that no applications are using it.
17+
If you delete a Valkey instance in use, the applications will lose access to the data stored in the instance.
18+
19+
### List Valkey instances
20+
21+
To list all Valkey instances belonging to your team:
22+
23+
1. Open [NAIS Console](https://console.<<tenant()>>.cloud.nais.io) in your browser and select your team.
24+
2. Select the `Valkey` tab
25+
3. Find the name of the Valkey instance you want to delete
26+
27+
### Disable termination protection
28+
29+
Before your can delete a specific Valkey instance, you must first disable termination protection.
30+
31+
To disable termination protection, run the following command:
32+
33+
```shell
34+
kubectl patch valkey <VALKEY-NAME> \
35+
--type json \
36+
-p='[{"op": "replace", "path": "/spec/terminationProtection", "value": false}]'
37+
```
38+
39+
### Delete Valkey instance
40+
41+
To delete the Valkey instance, run the following command:
42+
43+
```shell
44+
kubectl delete valkey <VALKEY-NAME>
45+
```
46+
47+
### Remove references from application manifests
48+
49+
Ensure that all references to the Valkey instance are removed from your application manifests:
50+
51+
```diff title="app.yaml"
52+
spec:
53+
- valkey:
54+
- - instance: <VALKEY-INSTANCE-NAME>
55+
- access: <ACCESS-LEVEL>
56+
```

0 commit comments

Comments
 (0)