Skip to content

Commit 7d19561

Browse files
baixinsuibaixinsui
authored
add cache docs for xpanse (#479)
1 parent 6685227 commit 7d19561

File tree

4 files changed

+154
-1
lines changed

4 files changed

+154
-1
lines changed

‎.github/vale/styles/config/vocabularies/xpanse/accept.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -47,4 +47,4 @@ Checkstyle
4747
dev
4848
formatters
4949
Checkstyle
50-
dev
50+
(?i)redis

‎docs/caching.mdx

+137
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
sidebar_position: 6
3+
---
4+
5+
import Link from '../src/components/link/Link';
6+
7+
# Caching
8+
9+
## Development Environments
10+
11+
For all development purposes, we use a local memory-based cache `Caffeine Cache` which is automatically created during the server startup.
12+
And when the service stops, all data in the local cache will be automatically cleared.
13+
14+
:::danger Caffeine Cache is only for development environments
15+
The Caffeine Cache is purely for development and test purposes only and must be avoided for production installation of xpanse.
16+
:::
17+
18+
## Production Environments
19+
20+
For production environments, we use a distributed cache. The below distributed caches are at the moment fully supported.
21+
By **support**, we mean configurations for the cache added and also all functionalities tested.
22+
23+
### Redis Cache
24+
25+
At the moment, this is the only distributed cache that's fully supported.
26+
To use `Redis` as the cache manager for xpanse, it must be activated by starting the application with profile `redis` and
27+
by replacing the placeholders for redis `host`, `port` and `password` as below.
28+
29+
```shell
30+
java -jar xpanse-runtime-*-SNAPSHOT.jar \
31+
-Dspring.profiles.active=redis \
32+
-Dspring.data.redis.host=${redis-host} \
33+
-Dspring.data.redis.port=${redis-port} \
34+
-Dspring.data.redis.password=${redis-password}
35+
```
36+
37+
#### Versions Supported
38+
39+
Current supported version of Redis is `7.4.2`. This is the latest LTS release of Redis.
40+
41+
#### Default Configuration
42+
43+
The default configuration parameters for redis profile can be found
44+
45+
<Link
46+
name={'here'}
47+
url={
48+
'https://github.com/eclipse-xpanse/xpanse/blob/main/runtime/src/main/resources/application-redis.properties#L6~L9'
49+
}
50+
/>
51+
.
52+
53+
#### Overriding Default Configuration
54+
55+
We can override the above three default configurations by starting the application as below by replacing the placeholders
56+
with actual values.
57+
58+
```shell
59+
java -jar xpanse-runtime-*-SNAPSHOT.jar \
60+
-Dspring.profiles.active=redis \
61+
-Dspring.data.redis.host=${replace-with-redis-host} \
62+
-Dspring.data.redis.port=${replace-with-redis-port} \
63+
-Dspring.data.redis.password=${replace-with-redis-password}
64+
65+
```
66+
67+
:::danger secrets better as environment variables
68+
It's safe to provide the redis-related properties as environment variables rather than passing them
69+
directly in the command line.
70+
In case of this,
71+
the same property name must be set in UPPERCASE and underscore separated instead of dot for all variables.
72+
:::
73+
74+
:::info network between xpanse and its redis
75+
Using this startup command, the redis can run on any machine that's reachable from the xpanse runtime application.
76+
:::
77+
78+
#### Redis as a Docker Container
79+
80+
Redis offers official Docker images for running a database as a container.
81+
More details can be found here on the official page of Redis
82+
website <Link name={'here'} url={'https://redis.io/docs/latest/operate/rs/installing-upgrading/quickstarts/docker-quickstart'}/> and on
83+
DockerHub <Link name={'here'} url={'https://hub.docker.com/_/redis/'}/>.
84+
85+
##### Starting new container
86+
87+
While starting the Redis docker container for the first time, we can configure `redis-port`, and
88+
`redis-password` as below and the same can be used in starting the xpanse runtime using the command described
89+
90+
<Link name={'above'} url={'./redis-cache#overriding-default-configuration'} isOpenInNewTab={false} />.
91+
92+
```shell
93+
docker pull redis:7.4.2
94+
```
95+
96+
By starting the container with the below command, the redis is started by automatically configuring the redis with
97+
xpanse redis port and password.
98+
99+
```shell
100+
docker run --name ${container-name} \
101+
-e REDIS_PASSWORD=${replace-with-redis-password}
102+
-p <replace-with-redis-port>:6379 -d redis:7.4.2
103+
```
104+
105+
:::tip Avoid secrets in command line
106+
To avoid passing database related properties in command line, we can use the ` --env-file` option of the `
107+
docker run` command to store all sensitive data.
108+
:::
109+
110+
## Cached Data
111+
112+
The application will cache multiple types of data. Each type of data cache will be registered into a cache manager with a specific name and configuration.
113+
There are two types of cache managers, one is for `Caffeine Cache` and the other is for `Redis Cache`.
114+
115+
Cache manager for Caffeine defined in the class `CaffeineCacheConfig`
116+
117+
<Link
118+
name={'here'}
119+
url={
120+
'https://github.com/eclipse-xpanse/xpanse/blob/main/modules/cache/src/main/java/org/eclipse/xpanse/modules/cache/CaffeineCacheConfig.java#L50~L60'
121+
}
122+
/>
123+
Cache manager for Redis defined in the class `RedisCacheConfig`
124+
<Link
125+
name={'here'}
126+
url={
127+
'https://github.com/eclipse-xpanse/xpanse/blob/main/modules/cache/src/main/java/org/eclipse/xpanse/modules/cache/RedisCacheConfig.java#L72~L86'
128+
}
129+
/>
130+
131+
In both cache managers, the following caches are created with the following names:
132+
133+
REGION_AZS_CACHE_NAME -- to cache different available zones of the regions in the service cloud providers.
134+
SERVICE_FLAVOR_PRICE_CACHE_NAME -- to cache different prices of the flavors of the service with different billing models in the service cloud providers.
135+
CREDENTIAL_CACHE_NAME -- to cache different credentials the service cloud providers provided by the users.
136+
MONITOR_METRICS_CACHE_NAME --to cache different monitor metrics of the deployed services.
137+
DEPLOYER_VERSIONS_CACHE_NAME --to cache available versions of the deployer tools, such as terraform, opentofu etc.

‎docs/developer-setup.mdx

+15
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,21 @@ If you wish to test with MySql, the MySql container can be started using the bel
101101
docker run --name mysql-db -p 3306:3306 -e MYSQL_PASSWORD=Xpanse@2023 -e MYSQL_ROOT_PASSWORD=xpanse -e MYSQL_DATABASE=xpanse -e MYSQL_USER=xpanse -d mysql:latest
102102
```
103103

104+
After the container is running, update the value of configuration `spring.profiles.active` in the xpanse application to append the profile value `mysql`.
105+
106+
### Redis Cache
107+
108+
By default, the development environment uses Caffeine Cache.
109+
Other than this, xpanse supports Redis Cache as well at the moment.
110+
111+
If you wish to test with Redis Cache, the Redis container can be started using the below command.
112+
113+
```shell
114+
docker run --name redis-cache -p 6379:6379 -e REDIS_PASSWORD=Xpanse@2023 -d redis:latest
115+
```
116+
117+
After the container is running, update the value of configuration `spring.profiles.active` in the xpanse application to append the profile value `redis`.
118+
104119
### Deployer Tools Installation
105120

106121
Depending on the type of deployers you intend to use,

‎docs/spring-profiles.mdx

+1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Each profile either enables a certain functionality or provides some default con
2424
| dev | Yes | to be used in all local development environments. |
2525
| opentelemetry | No | to enable OTEL instrumentation and forwarding. |
2626
| mysql | No | to enable MySQL database as persistence layer. |
27+
| redis | No | to enable Redis as distributed cache. |
2728
| test | Yes | Used in tests for having dummy configuration values. |
2829
| agent-api | No | Used when we want to deploy only the agent APIs. This is used for generating agent API schema and also to scale agent APIs independently. |
2930
| generate-openapi-doc | Yes | Used only to generate API documentation for swagger-hub. |

0 commit comments

Comments
 (0)