Skip to content

Commit b173778

Browse files
KevinGruber2001KevinGruber2001
committed
Update Chart Readme
1 parent 79128ba commit b173778

1 file changed

Lines changed: 104 additions & 82 deletions

File tree

‎chart/README.md‎

Lines changed: 104 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,45 @@
11
# theia-shared-cache Helm Chart
22

3-
Helm chart to deploy a custom Gradle Build Cache server with MinIO backend for Theia IDE deployments in Kubernetes.
3+
Helm chart to deploy a Gradle Build Cache server with Redis backend for Kubernetes.
44

55
## Architecture
66

7-
This chart deploys two components:
7+
This chart deploys the following components:
88

9-
1. **Cache Server** - A custom Go-based Gradle build cache server
10-
2. **MinIO** - S3-compatible object storage for cache data
9+
1. **Cache Server** - A Go-based Gradle build cache server
10+
2. **Redis** - In-memory storage for cache artifacts (with optional redis-exporter sidecar)
11+
3. **Reposilite** (optional) - Maven/Gradle dependency proxy
1112

1213
```
13-
┌─────────────────────────────────────────────────────┐
14-
│ Kubernetes Cluster │
15-
│ │
16-
│ ┌─────────────────┐ ┌─────────────────────┐ │
17-
│ │ Cache Server │──────▶│ MinIO │ │
18-
│ │ (Deployment) │ │ (StatefulSet) │ │
19-
│ │ Port: 8080 │ │ Port: 9000 │ │
20-
│ └────────┬────────┘ └─────────────────────┘ │
21-
│ │ │
22-
│ ┌────────▼────────┐ │
23-
│ │ Service │◀──── Gradle Builds │
24-
│ │ Port: 8080 │ │
25-
│ └─────────────────┘ │
26-
└─────────────────────────────────────────────────────┘
14+
┌──────────────────────────────────────────────────────────┐
15+
│ Kubernetes Cluster │
16+
│ │
17+
│ ┌─────────────────┐ ┌─────────────────────────┐ │
18+
│ │ Cache Server │──────▶│ Redis (Deployment) │ │
19+
│ │ (Deployment) │ │ Port: 6379 │ │
20+
│ │ Port: 8080 │ │ + Exporter :9121 │ │
21+
│ └────────┬─────────┘ └─────────────────────────┘ │
22+
│ │ │
23+
│ ┌────────▼─────────┐ ┌─────────────────────────┐ │
24+
│ │ Service │ │ Reposilite (optional) │ │
25+
│ │ Port: 8080 │ │ Dependency proxy │ │
26+
│ └──────────────────┘ └─────────────────────────┘ │
27+
│ ▲ │
28+
│ Gradle Builds │
29+
└──────────────────────────────────────────────────────────┘
2730
```
2831

2932
## Features
3033

31-
- Custom Go-based cache server with MinIO storage backend
34+
- Go-based cache server with Redis storage backend
35+
- Auto-generated Redis password (stored in Kubernetes Secret)
3236
- Prometheus metrics endpoint (`/metrics`)
37+
- Redis metrics via redis-exporter sidecar
38+
- Optional ServiceMonitor for Prometheus Operator
3339
- Health checks (`/ping`, `/health`)
34-
- Basic authentication for cache operations
35-
- Persistent storage for MinIO data
36-
- Configurable resource limits
40+
- Role-based authentication (reader/writer roles)
41+
- Optional Reposilite dependency proxy
42+
- Kubernetes recommended labels (`app.kubernetes.io/*`)
3743

3844
## Quick Start
3945

@@ -47,10 +53,8 @@ helm install gradle-cache ./chart
4753

4854
```bash
4955
helm install gradle-cache ./chart \
50-
--set cacheServer.auth.password=mysecretpassword \
51-
--set minio.auth.accessKey=myaccesskey \
52-
--set minio.auth.secretKey=mysecretkey \
53-
--set minio.persistence.size=100Gi
56+
--set auth.password=mysecretpassword \
57+
--set metrics.serviceMonitor.enabled=true
5458
```
5559

5660
## Configuration
@@ -59,47 +63,54 @@ helm install gradle-cache ./chart \
5963

6064
| Parameter | Description | Default |
6165
|-----------|-------------|---------|
62-
| `cacheServer.replicaCount` | Number of cache server replicas | `1` |
63-
| `cacheServer.image.repository` | Cache server image repository | `ghcr.io/kevingruber/theia-shared-cache/gradle-cache` |
64-
| `cacheServer.image.tag` | Cache server image tag | `latest` |
65-
| `cacheServer.port` | Cache server port | `8080` |
66-
| `cacheServer.auth.enabled` | Enable authentication | `true` |
67-
| `cacheServer.auth.username` | Cache username | `gradle` |
68-
| `cacheServer.auth.password` | Cache password | `changeme` |
69-
| `cacheServer.config.maxEntrySizeMB` | Max cache entry size in MB | `100` |
70-
| `cacheServer.resources` | Resource limits/requests | See values.yaml |
71-
72-
### MinIO
66+
| `enabled` | Enable/disable the entire deployment | `true` |
67+
| `image.repository` | Cache server image repository | `ghcr.io/ls1intum/theia-shared-cache/gradle-cache` |
68+
| `image.tag` | Cache server image tag | `main` |
69+
| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
70+
| `auth.enabled` | Enable authentication | `true` |
71+
| `auth.username` | Cache username | `gradle` |
72+
| `auth.password` | Cache password | `changeme` |
73+
| `resources.cacheServer.requests.memory` | Memory request | `256Mi` |
74+
| `resources.cacheServer.requests.cpu` | CPU request | `100m` |
75+
| `resources.cacheServer.limits.memory` | Memory limit | `1Gi` |
76+
| `resources.cacheServer.limits.cpu` | CPU limit | `500m` |
77+
78+
### Redis
7379

7480
| Parameter | Description | Default |
7581
|-----------|-------------|---------|
76-
| `minio.enabled` | Deploy MinIO alongside cache server | `true` |
77-
| `minio.image.repository` | MinIO image repository | `minio/minio` |
78-
| `minio.image.tag` | MinIO image tag | `latest` |
79-
| `minio.auth.accessKey` | MinIO access key | `minioadmin` |
80-
| `minio.auth.secretKey` | MinIO secret key | `minioadmin` |
81-
| `minio.persistence.enabled` | Enable persistent storage | `true` |
82-
| `minio.persistence.size` | Storage size | `50Gi` |
83-
| `minio.persistence.storageClass` | Storage class | `""` (default) |
84-
| `minio.resources` | Resource limits/requests | See values.yaml |
82+
| `storage.db` | Redis database index (0-15) | `0` |
83+
| `resources.redis.requests.memory` | Memory request | `128Mi` |
84+
| `resources.redis.requests.cpu` | CPU request | `100m` |
85+
| `resources.redis.limits.memory` | Memory limit | `2Gi` |
86+
| `resources.redis.limits.cpu` | CPU limit | `1000m` |
8587

86-
### Metrics
88+
The Redis password is auto-generated on first install and persisted across `helm upgrade`. Both Redis and the cache server read it from the same Kubernetes Secret.
89+
90+
### TLS
8791

8892
| Parameter | Description | Default |
8993
|-----------|-------------|---------|
90-
| `metrics.enabled` | Enable Prometheus metrics | `true` |
91-
| `metrics.serviceMonitor.enabled` | Create ServiceMonitor (Prometheus Operator) | `false` |
94+
| `tls.enabled` | Enable TLS for the cache server | `false` |
95+
| `tls.secretName` | Kubernetes TLS Secret name | `""` |
9296

93-
### External Secret
97+
### Metrics
9498

9599
| Parameter | Description | Default |
96100
|-----------|-------------|---------|
97-
| `existingSecret` | Use existing secret for credentials | `""` |
101+
| `metrics.serviceMonitor.enabled` | Create ServiceMonitor for Prometheus Operator | `false` |
102+
| `metrics.serviceMonitor.interval` | Scrape interval | `15s` |
103+
104+
Prometheus pod annotations (`prometheus.io/scrape`, `prometheus.io/port`) are always included on pod templates for annotation-based discovery.
98105

99-
If using `existingSecret`, the secret must contain these keys:
100-
- `minio-access-key`
101-
- `minio-secret-key`
102-
- `cache-password`
106+
### Reposilite
107+
108+
| Parameter | Description | Default |
109+
|-----------|-------------|---------|
110+
| `reposilite.enabled` | Deploy Reposilite dependency proxy | `true` |
111+
| `reposilite.persistence.enabled` | Enable persistent storage | `true` |
112+
| `reposilite.persistence.size` | Storage size | `20Gi` |
113+
| `reposilite.persistence.storageClass` | Storage class | `csi-rbd-sc` |
103114

104115
## Gradle Configuration
105116

@@ -111,20 +122,17 @@ buildCache {
111122
remote<HttpBuildCache> {
112123
url = uri("http://<release-name>-cache:8080/cache/")
113124
credentials {
114-
username = "gradle"
115-
password = "your-password"
125+
username = "writer"
126+
password = "changeme-writer"
116127
}
117128
isPush = true
118129
}
119130
}
120131
```
121132

122-
Or via environment variables:
123-
124-
```bash
125-
export GRADLE_CACHE_URL=http://<release-name>-cache:8080/cache/
126-
export GRADLE_CACHE_USERNAME=gradle
127-
export GRADLE_CACHE_PASSWORD=your-password
133+
Enable caching in `gradle.properties`:
134+
```properties
135+
org.gradle.caching=true
128136
```
129137

130138
## Port Forwarding (Development)
@@ -141,33 +149,47 @@ curl http://localhost:8080/health
141149

142150
## Monitoring
143151

144-
If `metrics.enabled` is true, Prometheus metrics are available at `/metrics`:
152+
### Prometheus Metrics
145153

146-
```bash
147-
curl http://<release-name>-cache:8080/metrics
148-
```
154+
Cache server metrics at `/metrics`:
155+
156+
| Metric | Type | Description |
157+
|--------|------|-------------|
158+
| `gradle_cache_requests_total` | Counter | Total requests by method and status |
159+
| `gradle_cache_cache_hits_total` | Counter | Cache hit count |
160+
| `gradle_cache_cache_misses_total` | Counter | Cache miss count |
161+
| `gradle_cache_request_duration_seconds` | Histogram | Request latency |
162+
| `gradle_cache_entry_size` | Histogram | Cache entry sizes |
163+
164+
Redis metrics via redis-exporter sidecar at `:9121/metrics`:
165+
166+
| Metric | Type | Description |
167+
|--------|------|-------------|
168+
| `redis_memory_used_bytes` | Gauge | Redis memory consumption |
169+
| `redis_db_keys` | Gauge | Number of cached entries |
170+
| `redis_keyspace_hits_total` | Counter | Redis-level cache hits |
171+
| `redis_keyspace_misses_total` | Counter | Redis-level cache misses |
172+
173+
### Grafana Dashboard
149174

150-
Available metrics:
151-
- `cache_requests_total` - Total cache requests by method and status
152-
- `cache_hits_total` - Cache hit count
153-
- `cache_misses_total` - Cache miss count
154-
- `cache_request_duration_seconds` - Request duration histogram
155-
- `cache_entry_size_bytes` - Cache entry size histogram
175+
A pre-built dashboard is available at `src/deployments/grafana/dashboards/gradle-build-cache.json`. Import it into your Grafana instance for cache hit rate, latency, Redis memory, and error monitoring.
156176

157177
## Upgrading
158178

159-
### From 0.1.x to 0.2.0
179+
### From 0.2.x to 0.3.0
160180

161-
Version 0.2.0 is a breaking change that replaces the official Gradle cache node with a custom implementation.
181+
Version 0.3.0 is a breaking change that replaces MinIO with Redis.
162182

163183
Changes:
164-
- New image: custom Go-based cache server instead of `gradle/build-cache-node`
165-
- New storage: MinIO backend instead of local PersistentVolume
166-
- New port: 8080 instead of 5071
167-
- New authentication: Basic auth built into cache server
184+
- Storage backend: MinIO (S3-compatible) replaced with Redis (in-memory)
185+
- Redis password auto-generated (no manual credential config)
186+
- MinIO StatefulSet replaced with Redis Deployment
187+
- Redis exporter sidecar for Prometheus metrics
188+
- Helm labels updated to `app.kubernetes.io/*` standard
189+
- Reader/writer role-based authentication
168190

169191
Migration steps:
170-
1. Back up any important cache data (usually safe to lose)
192+
1. Cache data cannot be migrated — the cache will start cold
171193
2. Uninstall the old release: `helm uninstall <release-name>`
172-
3. Install the new version with updated values
173-
4. Update Gradle configuration to use new port and credentials
194+
3. Install the new version: `helm install <release-name> ./chart`
195+
4. Gradle builds repopulate the cache automatically

0 commit comments

Comments
 (0)