---

name: helm-chart-upgrade-with-config-preservation description: Upgrades a Helm chart to a specific version while preserving existing configurations from a values file and ensuring the application remains operational. Handles the complete upgrade workflow including state discovery, compatibility resolution, configuration updates, execution, monitoring, and verification.

Instructions

1. Discover Current State & Environment

• Locate Workspace Files: List the workspace directory to find configuration files (config/) and kubeconfigs (k8s_configs/).
• Check Kubernetes Context: Verify the active or available Kubernetes cluster contexts.
• Read Values File: Load the user-specified values YAML file (e.g., config/redis-values.yaml) to understand the current configuration.
• Verify Target Namespace: Confirm the target namespace (e.g., shared-services) exists.
• Check Current Helm Release: Use helm list -n <namespace> with the correct kubeconfig to find the current chart name and version.
• Check Pod Status: List pods in the target namespace to establish a baseline health state.

2. Identify & Resolve Compatibility Issues

• Compare Values: Retrieve the previously applied Helm values (helm get values --revision <N>) to identify any runtime configurations (like image repositories) not present in the static values file.
• Analyze Upgrade Errors: If the initial upgrade fails (e.g., due to image pull errors or security warnings), inspect the pod events and StatefulSet specs to diagnose the root cause (e.g., ErrImagePull).
• Common Fixes: Be prepared to handle:
  • Image Repository Changes: Newer Bitnami charts may require using bitnamilegacy/ repositories. Add image.repository, sentinel.image.repository, metrics.image.repository, volumePermissions.image.repository, and sysctl.image.repository fields to the values file.
  • Security Policy: Add global.security.allowInsecureImages: true to bypass non-standard container warnings.
• Update Values File: Edit the user's values YAML file in-place to incorporate the necessary compatibility fixes, ensuring no duplicate sections are created.

3. Execute the Helm Upgrade

• Run Upgrade Command: Execute helm upgrade <RELEASE_NAME> <REPO/CHART> --version <TARGET_VERSION> -n <NAMESPACE> -f <VALUES_FILE_PATH> --kubeconfig <KUBECONFIG_PATH>.
• Handle Kubeconfig: If the export command is not allowed, pass the kubeconfig path directly via the --kubeconfig flag.

4. Monitor & Remediate Deployment

• Watch Pod Status: After the upgrade, immediately check the status of all pods in the namespace. Look for Pending, ErrImagePull, ImagePullBackOff, or CrashLoopBackOff states.
• Inspect Stuck Pods: Use kubectl describe pod <name> to get detailed events and identify why pods are not becoming Ready.
• Force Pod Recreation: If StatefulSets have updated revisions but old pods persist with outdated images, delete the problematic pods (kubectl delete pod <name>). The StatefulSet controller will recreate them with the new spec.
• Wait for Readiness: Poll pod status until all pods show READY (e.g., 1/1) and STATUS: Running. Allow time for startup and readiness probes to pass.

5. Verify Successful Upgrade

• Confirm Helm Revision: Verify helm list shows the correct new chart version and STATUS: deployed.
• Check StatefulSet Health: Confirm all StatefulSets show READY replicas matching the desired count (e.g., 1/1, 2/2).
• Validate Applied Values: Run helm get values to ensure all configurations from the updated values file are present.
• Final Health Check: Perform a final check that all application pods are Ready and services exist.

Key Triggers & User Intent

• The user requests to upgrade a specific Helm chart to an exact version.
• The user emphasizes preserving configurations from a named values YAML file.
• The user requires the application (pods) to be running properly after the upgrade.
• Keywords: upgrade, helm chart, version X.X.X, values.yaml, ensure configurations remain effective.

Critical Notes

• Image Compatibility: The trajectory shows a common issue where Bitnami's public image registry changed. Always check and specify bitnamilegacy/ repositories if standard pulls fail.
• StatefulSet Rollout: Helm upgrades may not immediately replace existing Pods in StatefulSets. Manual pod deletion is often required to force recreation with new images.
• Security Warnings: Adding global.security.allowInsecureImages: true is necessary when using non-standard images but carries security implications. The skill should document this trade-off.
• Idempotency: The steps are designed to be re-runnable. Checking state before making changes prevents unnecessary operations.