mirror of
https://github.com/cozystack/cozystack.git
synced 2026-11-09 05:25:14 +09:00
Aleksei Sviridkin
5af5962edf
Annotate storageClass as immutable across every stateful app whose chart exposes one — clickhouse, foundationdb, harbor, http-cache, kafka (Kafka + ZooKeeper), kubernetes (top-level only), mariadb, mongodb, nats, openbao, opensearch, postgres, qdrant, rabbitmq, redis, vm-disk. Without coverage across the catalogue the UI would render storageClass read-only on some apps and editable on others — a worse mental model than uniform behaviour. The annotation lands at the schema layer (CEL XValidation rule 'self == oldSelf' on values.schema.json / types.go / embedded openAPISchema in cozyrds/<app>.yaml). The cozystack aggregated apiserver does not yet evaluate CEL on application-backed resources; that is tracked at cozystack/cozystack#2657. The UI (cozystack/cozystack-ui#6) consumes the marker today. The PVC-pinning argument is identical for every chart: Kubernetes fixes a PVC's storageClassName at creation time, so editing this field on an existing resource never migrated data. The schema annotation makes that contract explicit. kubernetes.nodeGroups[name].storageClass is intentionally NOT annotated: the field is optional and undefaulted, so a strict 'self == oldSelf' rule would block any future attempt to set it on an existing node group. A richer ratcheting form is needed there — see docs/storage-immutability.md. A refactor in pkg/registry/apps/application/rest.go extracts the inline schema-build path into buildSpecSchema so it can be unit-tested. Three regression tests in rest_spec_schema_test.go pin the contract that x-kubernetes-validations survives the v1->internal->structural conversion (loaded from the actual MariaDB ApplicationDefinition fixture on disk, not a hand-edited mock). Each per-app README gains a one-line blockquote pointing to a new docs/storage-immutability.md that explains the contract and which consumers enforce it today. Requires cozystack/cozyvalues-gen with @immutable support — bump the pre-commit pin in .github/workflows/pre-commit.yml once the release exists. Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Aleksei Sviridkin <f@lex.la>
143 lines
7.4 KiB
Markdown
143 lines
7.4 KiB
Markdown
# Managed Nginx-based HTTP Cache Service
|
|
|
|
The Nginx-based HTTP caching service is designed to optimize web traffic and enhance web application performance.
|
|
This service combines custom-built Nginx instances with HAProxy for efficient caching and load balancing.
|
|
|
|
## Deployment information
|
|
|
|
The Nginx instances include the following modules and features:
|
|
|
|
- VTS module for statistics
|
|
- Integration with ip2location
|
|
- Integration with ip2proxy
|
|
- Support for 51Degrees
|
|
- Cache purge functionality
|
|
|
|
HAproxy plays a vital role in this setup by directing incoming traffic to specific Nginx instances based on a consistent hash calculated from the URL. Each Nginx instance includes a Persistent Volume Claim (PVC) for storing cached content, ensuring fast and reliable access to frequently used resources.
|
|
|
|
## Deployment Details
|
|
|
|
The deployment architecture is illustrated in the diagram below:
|
|
|
|
```
|
|
|
|
┌─────────┐
|
|
│ metallb │ arp announce
|
|
└────┬────┘
|
|
│
|
|
│
|
|
┌───────▼───────────────────────────┐
|
|
│ kubernetes service │ node
|
|
│ (externalTrafficPolicy: Local) │ level
|
|
└──────────┬────────────────────────┘
|
|
│
|
|
│
|
|
┌────▼────┐ ┌─────────┐
|
|
│ haproxy │ │ haproxy │ loadbalancer
|
|
│ (active)│ │ (backup)│ layer
|
|
└────┬────┘ └─────────┘
|
|
│
|
|
│ balance uri whole
|
|
│ hash-type consistent
|
|
┌──────┴──────┬──────────────┐
|
|
┌───▼───┐ ┌───▼───┐ ┌───▼───┐ caching
|
|
│ nginx │ │ nginx │ │ nginx │ layer
|
|
└───┬───┘ └───┬───┘ └───┬───┘
|
|
│ │ │
|
|
┌────┴───────┬─────┴────┬─────────┴──┐
|
|
│ │ │ │
|
|
┌───▼────┐ ┌────▼───┐ ┌───▼────┐ ┌────▼───┐
|
|
│ origin │ │ origin │ │ origin │ │ origin │
|
|
└────────┘ └────────┘ └────────┘ └────────┘
|
|
|
|
```
|
|
|
|
## Known issues
|
|
|
|
- VTS module shows wrong upstream response time, [github.com/vozlt/nginx-module-vts#198](https://github.com/vozlt/nginx-module-vts/issues/198)
|
|
|
|
> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it.
|
|
|
|
## Parameters
|
|
|
|
### Common parameters
|
|
|
|
| Name | Description | Type | Value |
|
|
| -------------- | ------------------------------------------------------------ | ---------- | ------- |
|
|
| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` |
|
|
| `storageClass` | StorageClass used to store the data. | `string` | `""` |
|
|
| `external` | Enable external access from outside the cluster. | `bool` | `false` |
|
|
|
|
|
|
### Application-specific parameters
|
|
|
|
| Name | Description | Type | Value |
|
|
| ----------- | ------------------------------------------------ | ---------- | ----- |
|
|
| `endpoints` | Endpoints configuration, as a list of <ip:port>. | `[]string` | `[]` |
|
|
|
|
|
|
### HAProxy parameters
|
|
|
|
| Name | Description | Type | Value |
|
|
| -------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | --------- |
|
|
| `haproxy` | HAProxy configuration. | `object` | `{}` |
|
|
| `haproxy.replicas` | Number of HAProxy replicas. | `int` | `2` |
|
|
| `haproxy.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` |
|
|
| `haproxy.resources.cpu` | CPU available to each replica. | `quantity` | `""` |
|
|
| `haproxy.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` |
|
|
| `haproxy.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` |
|
|
|
|
|
|
### Nginx parameters
|
|
|
|
| Name | Description | Type | Value |
|
|
| ------------------------ | -------------------------------------------------------------------------------------------------------- | ---------- | --------- |
|
|
| `nginx` | Nginx configuration. | `object` | `{}` |
|
|
| `nginx.replicas` | Number of Nginx replicas. | `int` | `2` |
|
|
| `nginx.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` |
|
|
| `nginx.resources.cpu` | CPU available to each replica. | `quantity` | `""` |
|
|
| `nginx.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` |
|
|
| `nginx.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` |
|
|
|
|
|
|
## Parameter examples and reference
|
|
|
|
### resources and resourcesPreset
|
|
|
|
`resources` sets explicit CPU and memory configurations for each replica.
|
|
When left empty, the preset defined in `resourcesPreset` is applied.
|
|
|
|
```yaml
|
|
resources:
|
|
cpu: 4000m
|
|
memory: 4Gi
|
|
```
|
|
|
|
`resourcesPreset` sets named CPU and memory configurations for each replica.
|
|
This setting is ignored if the corresponding `resources` value is set.
|
|
|
|
| Preset name | CPU | memory |
|
|
|-------------|--------|---------|
|
|
| `nano` | `250m` | `128Mi` |
|
|
| `micro` | `500m` | `256Mi` |
|
|
| `small` | `1` | `512Mi` |
|
|
| `medium` | `1` | `1Gi` |
|
|
| `large` | `2` | `2Gi` |
|
|
| `xlarge` | `4` | `4Gi` |
|
|
| `2xlarge` | `8` | `8Gi` |
|
|
|
|
|
|
### endpoints
|
|
|
|
`endpoints` is a flat list of IP addresses:
|
|
|
|
```yaml
|
|
endpoints:
|
|
- 10.100.3.1:80
|
|
- 10.100.3.11:80
|
|
- 10.100.3.2:80
|
|
- 10.100.3.12:80
|
|
- 10.100.3.3:80
|
|
- 10.100.3.13:80
|
|
```
|