Upgrading to a new version of the helm chart

This page contains information on how to upgrade a helm release. There are few considerations listed in the Considerations section where it is recommended for users to go through the whole document before proceeding with a helm release upgrade.

Users should be able to perform a helm release upgrade without any major issue if there is no change of service type involved in the new version of helm release. Check the Release Notes for more information about the changes in the new version of helm release.

Prerequisites

Before upgrading a helm release you must:
  • Understand the differences between NodePort service and ClusterIP service.
  • Obtain the following information regarding the current helm release:
    • The release name. This can be obtained using helm ls.
    • The service name. Use the kubectl get svc -l release=={{release_name}} command and substitute {{release_name}} with the value from above.
    • The current service resource type (NodePort or ClusterIP). Use kubectl describe svc {{service_name}} where {{service_name}} is the value obtained from above to get the service type. The service type is indicated by the Type attribute.
  • Know the planned service resource type for the upgrade (NodePort or ClusterIP).
  • Be an administrator or cluster administrator is required. You must have the correct role and permissions.
  • Have a new version of helm chart available for upgrade.

Considerations

If you are planning to change the service type from NodePort to ClusterIP during the helm release upgrade, then the following section applies.

Warning: There is a potential issue if you want to perform a helm upgrade that involves the change of service type from NodePort to ClusterIP. To check whether your helm release upgrade will encounter the issue, follow the steps in the next section.

Before proceeding, you should do a dry-run test to determine if the schedule for the upgrade chart might run into this issue. The dry-run provides you with the new service name for verification purposes.

If the helm chart will run into the issue, see the workaround section below.

Tip: You should only perform the workaround in a maintenance window because there may be a temporary service disruption.

Verifying the service name of the new helm chart using dry-run

To verify the service name of the new helm chart, use the following steps:
  1. Extract the helm chart from the software package using the following tar command: tar -zxvf ibm-cloud-netcool-probe-2.8.2-x86_64.tar.gz charts/ibm-netcool-probe-1.0.0.tgz

    Identify the version of the helm chart using the command tar -tvf ibm-cloud-netcool-probe-2.8.2-x86_64.tar.gz

  2. Perform a dry run by using the command: helm upgrade tutorial charts/ibm-netcool-probe-2.0.0.tgz --debug --dry-run --tls
  3. From the output of the helm, install in debug mode. Identify the template that has value Service for parameter kind. The name of the service is included in the metadata section under the parameter name.
    # Source: ibm-netcool-probe/templates/probe-logstash-service.yaml
# Service.yaml required to expose the IP address of the probe for 
# receiving notification.
apiVersion: v1
kind: Service
metadata:
  name: demo-probe-logstash
  4. Compare the service name with the existing helm release service name. If the service name is different, then proceed to the subsequent sections to upgrade the helm release using the command line or the ICP UI. Otherwise, refer to the Service type conversion issue and workaround section.

Performing a Helm release upgrade using the CLI

To perform a helm release upgrade using the CLI, run the following command provided: helm upgrade <release name> <chart directory> -f my-values.yaml using the configuration specified in the customized values.yaml file.

After a successful upgrade, the helm will return the following message. Release "tutorial" has been upgraded. Happy Helming!

where tutorial is the release name. You will also see the newly generated output in NOTES.txt.

Performing a Helm Release Upgrade using the ICP UI

To upgrade the helm release from ICP UI, use the following the steps:
  1. Click on Workloads > Helm Releases.
  2. Select the correct helm chart.
  3. Look for AVAILABLE VERSION in the Details and Upgrades section.
  4. Go through the Release Notes that are available under the version number for any major changes.
  5. Click on Upgrade, then select the correct repository and version from the drop drop list.
  6. Edit the necessary parameters in values.yaml.
  7. Click on Upgrade.
  8. Wait for the confirmation message and the update on the status of the release beside the release name on the top left hand corner of the UI.

Additional configuration to expose the service using ClusterIP

To allow an external network to reach the ClusterIP service, additional configurations must be performed. For a better understanding of the required additional steps, see Changing the service type during a helm upgrade.

Service Type conversion issue and workaround

Due to a known error when converting a NodePort to ClusterIP service type during a helm release upgrade or rollback, you can carry out one of the following workarounds before performing the helm release upgrade:
  1. Install the new version of the helm chart with a different release name and update all clients to point to the new probe service endpoint if required. Then delete the old release. This is the recommended method but requires a re-configuration on the client side.
  2. Manually change the service type using kubectl edit svc. This method requires more manual steps but preserves the current service name and previous revisions of the helm chart. After performing this workaround, users should be able to perform a helm upgrade.
  3. Delete and purge the existing helm release, and then install the new version of helm chart with the same release name.

These three methods are described in detail in Changing the service type during a helm upgrade.