From 05bbf05eabeeb15a4e6df248ce343887458e2fd5 Mon Sep 17 00:00:00 2001 From: Gandalf Date: Sat, 16 May 2026 12:27:58 -0300 Subject: [PATCH 1/2] docs(plugin-br-payments): add v1.0 upgrade guide Requested-by: @guimoreirar --- charts/plugin-br-payments/docs/UPGRADE-1.0.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 charts/plugin-br-payments/docs/UPGRADE-1.0.md diff --git a/charts/plugin-br-payments/docs/UPGRADE-1.0.md b/charts/plugin-br-payments/docs/UPGRADE-1.0.md new file mode 100644 index 00000000..9c796009 --- /dev/null +++ b/charts/plugin-br-payments/docs/UPGRADE-1.0.md @@ -0,0 +1,70 @@ +# Helm Upgrade from v0.x to v1.x +## Topics +- **[Overview](#overview)**- **[Version changes](#version-changes)**- **[Configuration changes](#configuration-changes)**- **[Breaking changes to review](#breaking-changes-to-review)**- **[Template changes](#template-changes)**- **[Migration steps](#migration-steps)**- **[Preview changes before upgrading](#preview-changes-before-upgrading)**- **[Command to upgrade](#command-to-upgrade)** + +## Overview +This guide covers the `plugin-br-payments` chart upgrade from `0.1.0` to `1.0.0-beta.1`. It was generated retroactively from the chart history and focuses on major version changes; patch-only releases are intentionally ignored. + +Because this is a major upgrade, review all removed values, renamed templates, and changed defaults before applying it to production. + +## Version changes + +| Field | Previous | Current | +|-------|----------|---------| +| Chart version | `0.1.0` | `1.0.0-beta.1` | +| App version | `1.0.0-beta.9` | `1.0.0-beta.9` | + +## Configuration changes + +### Added values + +_No direct values.yaml key changes detected._ + +### Removed values + +_No direct values.yaml key changes detected._ + +### Changed operational values + +_No image, env, secret, probe, ingress, service, port, or enablement changes detected in values.yaml._ + +## Breaking changes to review + +No removed values were detected in `values.yaml`, but this is still a major chart version. Review the template changes below before rollout. + +## Template changes + +### Added files + +- No chart files added. + +### Removed files + +- No chart files removed. + +### Modified files + +- `charts/plugin-br-payments/Chart.yaml` + +## Migration steps + +1. Read this guide and compare your custom values against `charts/plugin-br-payments/values.yaml`. +2. Add any required new values for your environment, especially secrets, configmaps, probes, ingress, and service settings. +3. Render the chart locally with your production values and review the manifest diff. +4. Apply the upgrade in a controlled environment before production. + +## Preview changes before upgrading + +```bash +helm diff upgrade plugin-br-payments ./charts/plugin-br-payments \ + --namespace \ + --values +``` + +## Command to upgrade + +```bash +helm upgrade plugin-br-payments ./charts/plugin-br-payments \ + --namespace \ + --values +``` From 2ef231c71b8c15ae3142358ecee27c686604605b Mon Sep 17 00:00:00 2001 From: Gandalf Date: Fri, 29 May 2026 11:50:52 -0300 Subject: [PATCH 2/2] docs(plugin-br-payments): align upgrade guide format Requested-by: @guimoreirar --- charts/plugin-br-payments/docs/UPGRADE-1.0.md | 109 ++++++++++++------ 1 file changed, 71 insertions(+), 38 deletions(-) diff --git a/charts/plugin-br-payments/docs/UPGRADE-1.0.md b/charts/plugin-br-payments/docs/UPGRADE-1.0.md index 9c796009..a6fb3fde 100644 --- a/charts/plugin-br-payments/docs/UPGRADE-1.0.md +++ b/charts/plugin-br-payments/docs/UPGRADE-1.0.md @@ -1,70 +1,103 @@ # Helm Upgrade from v0.x to v1.x -## Topics -- **[Overview](#overview)**- **[Version changes](#version-changes)**- **[Configuration changes](#configuration-changes)**- **[Breaking changes to review](#breaking-changes-to-review)**- **[Template changes](#template-changes)**- **[Migration steps](#migration-steps)**- **[Preview changes before upgrading](#preview-changes-before-upgrading)**- **[Command to upgrade](#command-to-upgrade)** - -## Overview -This guide covers the `plugin-br-payments` chart upgrade from `0.1.0` to `1.0.0-beta.1`. It was generated retroactively from the chart history and focuses on major version changes; patch-only releases are intentionally ignored. -Because this is a major upgrade, review all removed values, renamed templates, and changed defaults before applying it to production. +## Topics -## Version changes +- **[Overview](#overview)** +- **[Features](#features)** + - [1. Rename PROVIDER_* values to BTG_*](#1-rename-provider_-values-to-btg_) +- **[Configuration Changes](#configuration-changes)** +- **[Migration Steps](#migration-steps)** +- **[Preview changes before upgrading](#preview-changes-before-upgrading)** +- **[Command to upgrade](#command-to-upgrade)** -| Field | Previous | Current | -|-------|----------|---------| -| Chart version | `0.1.0` | `1.0.0-beta.1` | -| App version | `1.0.0-beta.9` | `1.0.0-beta.9` | +## Overview -## Configuration changes +This guide covers the `plugin-br-payments` chart upgrade from `0.1.0` to `1.0.0`. The application version remains `1.0.0-beta.9`; the chart bump to `1.0.0` carries a single breaking change: the provider integration value keys were renamed from the generic `PROVIDER_*` prefix to the vendor-specific `BTG_*` prefix to match the names the running binary actually reads. -### Added values +Existing deployments must rename these keys in their values overlays in the same change set that pins the chart to `1.0.0`. The previous `PROVIDER_*` keys were never consumed by the application binary, so any environment that relied on them was already running without provider integration. -_No direct values.yaml key changes detected._ +## Features -### Removed values +### 1. Rename PROVIDER_* values to BTG_* -_No direct values.yaml key changes detected._ +All provider integration keys were renamed from `PROVIDER_*` to `BTG_*` across `values.yaml`, `values-template.yaml`, `templates/_helpers.tpl`, `templates/NOTES.txt`, and `README.md`. The chart `fail` hooks were updated accordingly, so a deployment that still sets the old keys will be rejected at install/upgrade time with an explicit error. -### Changed operational values +| Section | Previous (v0.x) | Current (v1.0.0) | +|---------|-----------------|------------------| +| `app.configmap` | `PROVIDER_API_BASE_URL` | `BTG_API_BASE_URL` | +| `app.configmap` | `PROVIDER_AUTH_URL` | `BTG_AUTH_URL` | +| `app.configmap` | `PROVIDER_TOKEN_REFRESH_INTERVAL` | `BTG_TOKEN_REFRESH_INTERVAL` | +| `app.secrets` | `PROVIDER_CLIENT_ID` | `BTG_CLIENT_ID` | +| `app.secrets` | `PROVIDER_CLIENT_SECRET` | `BTG_CLIENT_SECRET` | +| `app.secrets` | `PROVIDER_WEBHOOK_SECRET` | `BTG_WEBHOOK_SECRET` | -_No image, env, secret, probe, ingress, service, port, or enablement changes detected in values.yaml._ +Updated `values.yaml` fragment: -## Breaking changes to review +```yaml +app: + configmap: + # BTG Provider Integration (REQUIRED - validated by helper) + BTG_API_BASE_URL: "" + BTG_AUTH_URL: "" + BTG_TOKEN_REFRESH_INTERVAL: "1h" + secrets: + # BTG OAuth2 (REQUIRED) + BTG_CLIENT_ID: "" + BTG_CLIENT_SECRET: "" + BTG_WEBHOOK_SECRET: "" +``` -No removed values were detected in `values.yaml`, but this is still a major chart version. Review the template changes below before rollout. +> **Note:** The application reads only the `BTG_*` names (see `internal/bootstrap/config.go` in `plugin-br-payments`). Environments that previously set `PROVIDER_*` keys were not driving the token reconciliation worker, even if the chart accepted the values. -## Template changes +## Configuration Changes -### Added files +The only configuration change in v1.0.0 is the rename described above. No new values were added, no values were removed beyond the rename, and no defaults for image, resources, probes, ingress, service, or replica counts were changed. -- No chart files added. +| Setting | v0.x | v1.0.0 | +|---------|------|--------| +| `app.configmap.PROVIDER_API_BASE_URL` | present | removed (renamed) | +| `app.configmap.PROVIDER_AUTH_URL` | present | removed (renamed) | +| `app.configmap.PROVIDER_TOKEN_REFRESH_INTERVAL` | present | removed (renamed) | +| `app.secrets.PROVIDER_CLIENT_ID` | present | removed (renamed) | +| `app.secrets.PROVIDER_CLIENT_SECRET` | present | removed (renamed) | +| `app.secrets.PROVIDER_WEBHOOK_SECRET` | present | removed (renamed) | +| `app.configmap.BTG_API_BASE_URL` | n/a | required | +| `app.configmap.BTG_AUTH_URL` | n/a | required | +| `app.configmap.BTG_TOKEN_REFRESH_INTERVAL` | n/a | `"1h"` default | +| `app.secrets.BTG_CLIENT_ID` | n/a | required | +| `app.secrets.BTG_CLIENT_SECRET` | n/a | required | +| `app.secrets.BTG_WEBHOOK_SECRET` | n/a | required | -### Removed files +## Migration Steps -- No chart files removed. +1. Update every values overlay that targets this chart to use the `BTG_*` keys instead of `PROVIDER_*`. Any leftover `PROVIDER_*` keys will be ignored by the chart (they no longer have a template binding). +2. Verify the renamed keys against the snippet above. The chart fails fast at install/upgrade time if any of the required `BTG_*` keys are empty. +3. Preview the rendered diff with the helm-diff plugin (see [Preview changes before upgrading](#preview-changes-before-upgrading)). +4. Run the upgrade command during a maintenance window. +5. Verify all pods are running and healthy after the upgrade: -### Modified files +```bash +kubectl get pods -n +``` -- `charts/plugin-br-payments/Chart.yaml` +6. Check service logs to confirm the token reconciliation worker reaches the BTG endpoints: -## Migration steps +```bash +kubectl logs -n -l app.kubernetes.io/name=plugin-br-payments-helm --tail=100 +``` -1. Read this guide and compare your custom values against `charts/plugin-br-payments/values.yaml`. -2. Add any required new values for your environment, especially secrets, configmaps, probes, ingress, and service settings. -3. Render the chart locally with your production values and review the manifest diff. -4. Apply the upgrade in a controlled environment before production. +> **Note:** The upgrade triggers a rolling restart of the plugin pods. Depending on your replica count and readiness probe configuration, this may cause brief request handling interruptions. ## Preview changes before upgrading ```bash -helm diff upgrade plugin-br-payments ./charts/plugin-br-payments \ - --namespace \ - --values +helm diff upgrade plugin-br-payments oci://registry-1.docker.io/lerianstudio/plugin-br-payments-helm --version 1.0.0 -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 plugin-br-payments ./charts/plugin-br-payments \ - --namespace \ - --values +helm upgrade plugin-br-payments oci://registry-1.docker.io/lerianstudio/plugin-br-payments-helm --version 1.0.0 -n ```