diff --git a/charts/reporter/docs/UPGRADE-2.3.md b/charts/reporter/docs/UPGRADE-2.3.md new file mode 100644 index 00000000..ebe5a6f5 --- /dev/null +++ b/charts/reporter/docs/UPGRADE-2.3.md @@ -0,0 +1,151 @@ +# Helm Upgrade from v2.2.x to v2.3.x + +## Topics + +- **[Overview](#overview)** +- **[Features](#features)** + - [1. Manager readiness path now defaults to /readyz](#1-manager-readiness-path-now-defaults-to-readyz) + - [2. Worker readiness path now defaults to /readyz](#2-worker-readiness-path-now-defaults-to-readyz) + - [3. Manager and worker probe paths are now configurable](#3-manager-and-worker-probe-paths-are-now-configurable) +- **[Configuration Changes](#configuration-changes)** +- **[Migration Steps](#migration-steps)** +- **[Preview changes before upgrading](#preview-changes-before-upgrading)** +- **[Command to upgrade](#command-to-upgrade)** + +## Overview + +This is a minor maintenance release that aligns the `manager` and `worker` readiness probes with the platform-wide `/readyz` convention and exposes both probe paths through `values.yaml`. The application version is unchanged. + +| Field | v2.2.x | v2.3.x | +|-------|--------|--------| +| Chart version | `2.2.1-beta.1` | `2.3.0-beta.1` | +| App version | `1.2.0` | `1.2.0` | + +## Features + +### 1. Manager readiness path now defaults to /readyz + +The `manager` deployment readiness probe HTTP path default has changed from `/health` to `/readyz`. The liveness probe default path remains `/health`. + +| Probe | v2.2.x default | v2.3.x default | +|-------|----------------|----------------| +| `manager.readinessProbe.path` | `/health` (hardcoded) | `/readyz` | +| `manager.livenessProbe.path` | `/health` (hardcoded) | `/health` | + +Rendered probe block in v2.3.x: + +```yaml +readinessProbe: + httpGet: + path: /readyz + port: +livenessProbe: + httpGet: + path: /health + port: +``` + +### 2. Worker readiness path now defaults to /readyz + +The `worker` deployment readiness probe HTTP path default has changed from `/ready` to `/readyz`. The liveness probe default path remains `/health`. + +| Probe | v2.2.x default | v2.3.x default | +|-------|----------------|----------------| +| `worker.readinessProbe.path` | `/ready` (hardcoded) | `/readyz` | +| `worker.livenessProbe.path` | `/health` (hardcoded) | `/health` | + +Rendered probe block in v2.3.x: + +```yaml +readinessProbe: + httpGet: + path: /readyz + port: +livenessProbe: + httpGet: + path: /health + port: +``` + +### 3. Manager and worker probe paths are now configurable + +Both manager and worker deployments now read the probe `path` from `values.yaml`, alongside the timing fields that were already configurable. No new top-level keys are introduced; the existing `manager.readinessProbe`, `manager.livenessProbe`, `worker.readinessProbe`, and `worker.livenessProbe` blocks now also accept `path`. + +| Key | v2.2.x | v2.3.x | +|-----|--------|--------| +| `manager.readinessProbe.path` | not honored (hardcoded `/health`) | overridable, defaults to `/readyz` | +| `manager.livenessProbe.path` | not honored (hardcoded `/health`) | overridable, defaults to `/health` | +| `worker.readinessProbe.path` | not honored (hardcoded `/ready`) | overridable, defaults to `/readyz` | +| `worker.livenessProbe.path` | not honored (hardcoded `/health`) | overridable, defaults to `/health` | + +Example override to keep prior behavior: + +```yaml +manager: + readinessProbe: + path: /health +worker: + readinessProbe: + path: /ready +``` + +## Configuration Changes + +No `values.yaml` keys were added, removed, or renamed. The change is in template defaults only. If your `values.yaml` does not pin probe paths, the readiness path will switch to `/readyz` automatically on upgrade. + +| Setting | v2.2.x | v2.3.x | Notes | +|---------|--------|--------|-------| +| `manager.readinessProbe.path` (default) | `/health` (hardcoded) | `/readyz` | Override to `/health` if your image does not serve `/readyz` | +| `manager.livenessProbe.path` (default) | `/health` (hardcoded) | `/health` | Now overridable via values | +| `worker.readinessProbe.path` (default) | `/ready` (hardcoded) | `/readyz` | Override to `/ready` if your image does not serve `/readyz` | +| `worker.livenessProbe.path` (default) | `/health` (hardcoded) | `/health` | Now overridable via values | + +## Migration Steps + +This upgrade requires no mandatory values changes. The Helm upgrade will roll the manager and worker deployments and update probe paths. + +**Recommended upgrade process:** + +1. Review the changes using the helm-diff plugin (see [Preview changes before upgrading](#preview-changes-before-upgrading)). +2. Confirm that the deployed `reporter-manager` and `reporter-worker` images expose `/readyz`. If they do not, pin the prior paths in your values: + + ```yaml + manager: + readinessProbe: + path: /health + worker: + readinessProbe: + path: /ready + ``` + +3. Run the upgrade command during a maintenance window. +4. Verify all pods are running and healthy after the upgrade: + +```bash +kubectl get pods -n +``` + +5. Check probe behavior for both components: + +```bash +kubectl logs -n -l app.kubernetes.io/name=reporter-manager --tail=50 +kubectl logs -n -l app.kubernetes.io/name=reporter-worker --tail=50 +kubectl describe pod -n -l app.kubernetes.io/name=reporter-manager | grep -A2 -E "Liveness|Readiness" +kubectl describe pod -n -l app.kubernetes.io/name=reporter-worker | grep -A2 -E "Liveness|Readiness" +``` + +> **Note:** The upgrade triggers a rolling restart of both the manager and worker deployments. If a new readiness path returns non-2xx, pods will not become Ready and the rollout will pause. + +## Preview changes before upgrading + +```bash +helm diff upgrade reporter oci://registry-1.docker.io/lerianstudio/reporter-helm --version 2.3.0-beta.1 -n +``` + +> **Note:** Requires the [helm-diff plugin](https://github.com/databus23/helm-diff). Install with: `helm plugin install https://github.com/databus23/helm-diff` + +## Command to upgrade + +```bash +helm upgrade reporter oci://registry-1.docker.io/lerianstudio/reporter-helm --version 2.3.0-beta.1 -n +```