Skip to content

docs(fetcher): add v2.2 upgrade guide #1380

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
guimoreirar merged 2 commits into from
May 29, 2026
+99 −0
Merged

docs(fetcher): add v2.2 upgrade guide #1380

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
91162e8
docs(fetcher): add v2.2 upgrade guide
gandalf-at-lerian May 16, 2026
7360754
docs(fetcher): align upgrade guide format
gandalf-at-lerian May 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 99 additions & 0 deletions charts/fetcher/docs/UPGRADE-2.2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# Helm Upgrade from v2.1.x to v2.2.x

## Topics

- **[Overview](#overview)**
- **[Features](#features)**
- [1. Configurable liveness and readiness probe paths](#1-configurable-liveness-and-readiness-probe-paths)
- [2. New `successThreshold` knob on manager probes](#2-new-successthreshold-knob-on-manager-probes)
- **[Configuration Changes](#configuration-changes)**
- **[Migration Steps](#migration-steps)**
- **[Preview changes before upgrading](#preview-changes-before-upgrading)**
- **[Command to upgrade](#command-to-upgrade)**

## Overview

This guide covers the `fetcher` chart upgrade from `2.1.1` to `2.2.0-beta.4`. It is a minor maintenance release that makes the `manager` Deployment probes more flexible without changing existing behavior for users who do not override the new knobs.

The application image (`appVersion: 1.3.0`) is unchanged. No breaking changes, no required `values.yaml` modifications, and no data migration are needed.
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Clarify the impact of the readiness probe default change.

The document states "No breaking changes," but the readiness probe default changed from /health to /readyz (documented in line 29). If users' applications don't serve the /readyz endpoint, pods will fail readiness checks and be removed from service endpoints, which is a breaking behavioral change for those deployments.

Consider either:

  1. Revising "No breaking changes" to "No breaking changes if your application serves /readyz" or "Potentially breaking change: readiness probe path default changed"
  2. Moving the critical warning from line 31 into the Overview section to make the impact immediately clear
📝 Proposed fix to clarify breaking change potential 
-The application image (`appVersion: 1.3.0`) is unchanged. No breaking changes, no required `values.yaml` modifications, and no data migration are needed.
+The application image (`appVersion: 1.3.0`) is unchanged. No data migration is needed. **Important:** The readiness probe default path changed from `/health` to `/readyz`—verify your application serves this endpoint or set `manager.readinessProbe.path: /health` before upgrading (see [Configurable probe paths](`#1-configurable-liveness-and-readiness-probe-paths`)).
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@charts/fetcher/docs/UPGRADE-2.2.md` at line 18, Update the UPGRADE-2.2.md
text to make the readiness-probe change explicit: replace the sentence that
currently states "No breaking changes" with a conditional/qualified statement
such as "Potentially breaking change: readiness probe default changed from
`/health` to `/readyz` — ensure your app serves `/readyz` or adjust
values.yaml," and/or move the existing warning about readiness probes into the
Overview paragraph so it appears immediately; target the sentence containing "No
breaking changes" and the paragraph referencing the readiness probe path
("/readyz") for this edit.


## Features

### 1. Configurable liveness and readiness probe paths

The `manager` Deployment previously hard-coded `/health` for both liveness and readiness probes. Both paths are now configurable via values, with backwards-compatible defaults:

| Probe | v2.1.1 path | v2.2.0-beta.4 default | Override key |
|-------|-------------|------------------------|--------------|
| Liveness | `/health` | `/health` | `manager.livenessProbe.path` |
| Readiness | `/health` | `/readyz` | `manager.readinessProbe.path` |

> **Note:** The readiness probe default changed from `/health` to `/readyz`. If your `fetcher-manager` image still serves readiness on `/health`, set `manager.readinessProbe.path: /health` explicitly before upgrading.

```yaml
manager:
livenessProbe:
path: /health
readinessProbe:
path: /readyz
```

### 2. New `successThreshold` knob on manager probes

Both probes now honor a `successThreshold` value. If omitted, it defaults to `1`, matching the previous implicit behavior.

```yaml
manager:
livenessProbe:
successThreshold: 1
readinessProbe:
successThreshold: 1
```

## Configuration Changes

No `values.yaml` keys were added or removed. All new knobs are optional and fall back to safe defaults.

| Setting | v2.1.1 | v2.2.0-beta.4 |
|---------|--------|---------------|
| `manager.livenessProbe.path` | (hard-coded `/health`) | optional, defaults to `/health` |
| `manager.readinessProbe.path` | (hard-coded `/health`) | optional, defaults to `/readyz` |
| `manager.livenessProbe.successThreshold` | (not exposed) | optional, defaults to `1` |
| `manager.readinessProbe.successThreshold` | (not exposed) | optional, defaults to `1` |

## Migration Steps

This upgrade requires no manual migration steps. The Helm upgrade will roll the `manager` Deployment with the new probe template.

**Recommended upgrade process:**

1. Confirm which path your `fetcher-manager` image serves readiness on. If it is `/health`, pin it explicitly: `manager.readinessProbe.path: /health`.
2. Review the changes using the helm-diff plugin (see [Preview changes before upgrading](#preview-changes-before-upgrading)).
3. Run the upgrade command during a maintenance window.
4. Verify the manager pods are healthy after the upgrade:
Comment on lines +64 to +73
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Resolve contradiction between "no manual migration steps" and step 1.

Line 66 states "This upgrade requires no manual migration steps," but step 1 (line 70) instructs users to "pin it explicitly" if their application serves readiness on /health. Explicitly setting a configuration value to avoid breaking changes is a manual migration step.

📝 Proposed fix to resolve contradiction 
-This upgrade requires no manual migration steps. The Helm upgrade will roll the `manager` Deployment with the new probe template.
+The Helm upgrade will automatically roll the `manager` Deployment with the new probe template. If your application serves readiness on `/health` rather than `/readyz`, you must pin the probe path before upgrading (see step 1 below).
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@charts/fetcher/docs/UPGRADE-2.2.md` around lines 64 - 73, The doc currently
contradicts itself: "This upgrade requires no manual migration steps" but step 1
asks users to "pin" manager.readinessProbe.path, which is a manual change;
update the Migration Steps text to remove the contradiction by rephrasing the
first sentence and step 1 to indicate this is optional/precautionary (e.g., "No
manual migration required for most users; if your fetcher-manager serves
readiness on /health you may explicitly set manager.readinessProbe.path: /health
to avoid changes") and mark step 1 as an optional/recommended action rather than
a required migration.


```bash
kubectl get pods -n fetcher -l app.kubernetes.io/component=manager
```

5. Check manager logs for probe-related restarts:

```bash
kubectl logs -n fetcher -l app.kubernetes.io/component=manager --tail=50
```

> **Note:** A readiness probe pointing at a path the application does not serve will keep pods out of the Service endpoints. Verify the readiness path before upgrading in production.

## Preview changes before upgrading

```bash
helm diff upgrade fetcher oci://registry-1.docker.io/lerianstudio/fetcher-helm --version 2.2.0-beta.4 -n fetcher
```

> **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 fetcher oci://registry-1.docker.io/lerianstudio/fetcher-helm --version 2.2.0-beta.4 -n fetcher
```
Loading