Upgrading Releases
1. Upgrading Release
| Field | Description | Example |
|---|---|---|
| --set | Set values on the command line (can be used multiple times) | helm upgrade my-release my-chart --set image.tag=v2.0 |
| --set-string | Set string values on the command line (can be used multiple times) | helm upgrade my-release my-chart --set-string image.tag=v2.0 |
| --values | Specify values in a YAML file or URL | helm upgrade my-release my-chart -f values.yaml |
| --reuse-values | Reuse the last release's values and merge new values | helm upgrade my-release my-chart --reuse-values |
| --atomic | Rollback on failure | helm upgrade my-release my-chart --atomic |
| --timeout | Timeout for the upgrade operation (default 5m0s) | helm upgrade my-release my-chart --timeout 10m |
| --wait | Wait for all resources to be in a ready state | helm upgrade my-release my-chart --wait |
| --no-hooks | Prevent hooks from running during the upgrade | helm upgrade my-release my-chart --no-hooks |
Example: Upgrading a Release with New Values
helm upgrade my-release stable/nginx --set image.tag=v1.18 --set service.type=LoadBalancer
Note: When using
--reuse-values, any new values in the chart will not override existing ones unless explicitly overridden.
2. Installing or Upgrading
| Command | Description | Flags | Notes |
|---|---|---|---|
| helm install | Install a new release or upgrade an existing one | --set, --values, --namespace |
Can be used for both initial install and upgrades |
| helm upgrade | Upgrade an existing release to a new version | --set, --values, --version |
Useful for updating chart versions or values |
Example: Installing a Release
helm install my-app stable/nginx
helm install --set image.tag=v1.2.3 my-app stable/nginxExample: Upgrading a Release
helm upgrade my-app stable/nginx --version 1.2.3
helm upgrade --set image.tag=v2.0.0 my-app stable/nginx
Note: If a release already exists with the same name,
helm install will attempt to upgrade it. Use helm upgrade explicitly for upgrades.
3. Forcing Resource Update
When upgrading a Helm release, you might need to force an update of specific resources even if their configuration hasn't changed. This is useful for scenarios like:
- Re-applying a configuration change that was ignored due to a previous update
- Recreating resources with new labels or annotations
- Triggering a rollout of a Deployment even if the image digest remains the same
| Flag | Description | Usage |
|---|---|---|
| --force | Force resource update through delete and recreate if needed | helm upgrade --force my-release my-chart |
| --recreate-pods | Recreate pods for resources that support it (e.g., Deployments) | helm upgrade --recreate-pods my-release my-chart |
| --atomic | Rollback on failure during upgrade | helm upgrade --atomic my-release my-chart |
Note: Using
--force can cause downtime for resources like Deployments or Services, as they are deleted and recreated.
Warning: Forcing updates can lead to data loss or downtime, especially for resources like StatefulSets or PersistentVolumes.
4. Resetting Values
| Option | Description | Default |
|---|---|---|
| --reset-values | When specified, Helm will reset the values to the ones defined in the chart's default values.yaml file | false |
Note: Using
--reset-values will discard any custom values that were previously set, reverting to the chart's original defaults.
5. Reusing Previous Values
| Option | Description | Usage |
|---|---|---|
| --set | Set values on the command line | helm upgrade my-release my-chart --set key1=value1,key2=value2 |
| --set-string | Set string values on the command line | helm upgrade my-release my-chart --set-string key1=value1 |
| --set-file | Set values from a file | helm upgrade my-release my-chart --set-file key1=path/to/file |
| --values | Provide a YAML file with values to override | helm upgrade my-release my-chart -f values.yaml |
| --reuse-values | Reuse the last release's values and merge with new ones | helm upgrade my-release my-chart --reuse-values |
Note: When using
--reuse-values, any new values specified will override the previous ones.
6. Upgrading with New Values
| Field | Description | Example |
|---|---|---|
| --set | Set values on the command line (can be used multiple times) | helm upgrade my-release my-chart --set image.tag=v2.0 |
| --set-string | Set values as strings (useful for numeric values) | helm upgrade my-release my-chart --set-string replicas=3 |
| --set-file | Set values from a file (e.g., config files) | helm upgrade my-release my-chart --set-file config.yaml=./config.yaml |
| --values | Specify a YAML file containing values to override | helm upgrade my-release my-chart -f values.yaml |
Example: Upgrading with new values
helm upgrade my-release stable/nginx --set image.tag=v1.18 --set service.type=LoadBalancer
Note: When using
--set, values are merged with existing ones, and new keys will be added to the release.
7. Using Atomic Upgrades
Atomic upgrades in Helm ensure that either all resources are updated successfully or the entire upgrade is rolled back to the previous state, maintaining consistency and reliability.
| Option | Values | Description |
|---|---|---|
| --atomic | true |
Enables atomic upgrades. If the upgrade fails, it rolls back to the previous release. |
| --timeout | 300s |
Timeout for the upgrade operation (default is 5 minutes). |
| --wait | true |
Waits for all resources to be in a ready state before marking the upgrade as successful. |
Example: Performing an Atomic Upgrade
helm upgrade my-release my-chart --atomic --timeout 600s --wait
Note: Atomic upgrades are particularly useful in production environments where consistency and rollback capability are critical.
Warning: Ensure that your release has sufficient resources and dependencies to support the atomic upgrade process. Rolling back may not always be seamless if dependencies have changed.
8. Cleaning Up on Failed Upgrade
| Option | Values | Notes |
|---|---|---|
| --cleanup-on-fail | true |
Automatically delete the release on upgrade failure |
| --recreate-pods | false |
Recreate pods after upgrade failure (default) |
Note: When
--cleanup-on-fail is enabled, Helm will delete the release and its resources if the upgrade fails. This can help in maintaining a clean state but may result in data loss.Warning: Use
--cleanup-on-fail with caution in production environments where data persistence is critical.9. Setting Revision Limits
| Option | Values | Description |
|---|---|---|
| --history-limit | 10 |
Limits the number of revisions stored per release |
| --set | historyLimit=5 |
Set history limit during upgrade |
Note: Setting
--history-limit to 0 disables history tracking entirely.
10. Waiting for Upgrade Completion
| Option | Values | Description |
|---|---|---|
| --wait | true |
Will wait for all the resources to be in a ready state before marking the release as successful |
| --timeout | 300s |
Timeout for waiting for resources to become ready (default is 300 seconds) |
| --wait-for-jobs | false |
Will wait for all the jobs to complete before marking the release as successful |
Note: The
--wait flag ensures that the upgrade process waits until all resources are ready before marking the release as successful. This is particularly useful for ensuring that dependent services are fully operational after an upgrade.