Skip to content

Commit d14cd22

Browse files
baixinsuibaixinsui
committed
add cache docs for xpanse
1 parent e8a03d0 commit d14cd22

File tree

3 files changed

+134
-1
lines changed

3 files changed

+134
-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

+120
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
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 `Redis Cache`. By **support**, we mean configurations for the cache added and also all
21+
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 above command will start the xpanse runtime with the following default configurations:
44+
45+
1. Redis cache is enabled.
46+
2. Redis server running on the same machine where xpanse is running. (Same localhost)
47+
3. Redis server is listening on port `6379`.
48+
4. Required password for the Redis server is `Xpanse@2023`.
49+
50+
The Default configuration file can be
51+
found <Link name={'here'} url={'https://github.com/eclipse-xpanse/xpanse/blob/main/runtime/src/main/resources/application-redis.properties#L6~L9'}/>.
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 the different data with different cache managers as below.
113+
These different cache managers are configured in the `RedisCacheConfig` class with the following names and configuration methods.
114+
<Link name={'here'} url={'https://github.com/eclipse-xpanse/xpanse/blob/main/modules/cache/src/main/java/org/eclipse/xpanse/modules/cache/RedisCacheConfig.java#L79~L84'}/>.
115+
116+
REGION_AZS_CACHE_NAME -- to cache different available zones of the regions in the service cloud providers.
117+
SERVICE_FLAVOR_PRICE_CACHE_NAME -- to cache different prices of the flavors of the service with different billing models in the service cloud providers.
118+
CREDENTIAL_CACHE_NAME -- to cache different credentials the service cloud providers provided by the users.
119+
MONITOR_METRICS_CACHE_NAME --to cache different monitor metrics of the deployed services.
120+
DEPLOYER_VERSIONS_CACHE_NAME --to cache available versions of the deployer tools, such as terraform, opentofu etc.

‎docs/developer-setup.mdx

+13
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,19 @@ If you wish to test with MySql, the MySql container can be started using the bel
100100
```shell
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
```
103+
After the container is running, update the value of configuration `spring.profiles.active` in the xpanse application to append the profile value `mysql`.
104+
105+
### Redis Cache
106+
107+
By default, the development environment uses Caffeine Cache.
108+
Other than this, xpanse supports Redis Cache as well at the moment.
109+
110+
If you wish to test with Redis Cache, the Redis container can be started using the below command.
111+
112+
```shell
113+
docker run --name redis-cache -p 6379:6379 -d redis:latest
114+
```
115+
After the container is running, update the value of configuration `enable.redis.distributed.cache` in the xpanse application to `true`.
103116

104117
### Deployer Tools Installation
105118

0 commit comments

Comments
 (0)