AgentSkillsCN

helm-chart-upgrade-with-config-preservation

在保留values文件中现有配置的同时，将Helm图表升级至特定版本，并确保应用程序持续运行。该技能会完成整个升级流程：发现状态、解决兼容性问题、更新配置、执行、监控以及验证。

SKILL.md
--- frontmatter
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.