Backing up and upgrading License Service

Learn how to back up and upgrade License Service.

Independent License Service upgrade

License Service is a stand-alone component which does not depend on any other product or service.

License Service can be delivered as an individual component, as a part of IBM Cloud Pak® foundational services or IBM Cloud Pak®. In each case, you can upgrade License Service without the need to upgrade any other product. The upgrade does not affect any other products in any way.

Backing up License Service

License Service collects license usage data and stores this data in the persistent cluster memory. Thus, License Service data is not affected when you kill or restart a pod.

It is recommended to generate an audit snapshot periodically for backup purposes and store it in a safe location. You do not need to perform any other backup.

Note: Before decommissioning a cluster, generate an audit snapshot to record the license usage of the products until the day of decommissioning.

Upgrading License Service

Starting from License Service version 4.2, upgrades are automatic. However, if you use the older version of License Service, complete one of the following procedures to upgrade to the newest version and take full advantage of all License Service features.

Environment Current version Upgrading to the latest version
Online 4.2.x or later License Service is automatically upgraded with the latest operator release.
Online 4.0.x or 4.1.x Complete the following procedure: Upgrading License Service from version 4.0 or 4.1 to 4.2 or later.
Online 1.x Complete the following procedure: Upgrading License Service from version 1.x to 4.x.
Installation without OLM or Offline Any Back up the License Service ConfigMaps, Uninstall License Service, Install License Service and restore the License Service ConfigMaps. For more information about how to back up and restore ConfigMaps, see Upgrading License Service from version 1.x to 4.x.

Note: The license usage data is stored in the persistent cluster memory and must not be affected by reinstallation of License Service. It is recommended to create an audit snapshot before reinstalling License Service as a precaution.

Checking your current version

To check your current version of License Service, run the following command:

kubectl get clusterserviceversion -n ibm-licensing

Note: The ibm-licensing namespace is the default namespace of License Service. If you installed License Service in a custom namespace for your cluster, replace ibm-licensing with your custom namespace. This method is applicable only for online installations.

Upgrading License Service from version 4.0 or 4.1 to 4.2 or later

Upgrading License Service by using the CLI

  1. Log in to the cluster.

  2. Run the following commands to update the ibm-licensing-catalog CatalogSource with the latest release version.

    export NAMESPACE=$(kubectl get catalogsource -A | grep licensing | awk '{print $1}')
    export CATALOG_SOURCE=$(kubectl get catalogsource -A | grep licensing | awk '{print $2}')
    export GA_IMAGE="icr.io/cpopen/ibm-licensing-catalog"
    
    kubectl patch catalogsource $CATALOG_SOURCE -n $NAMESPACE \
     --type=merge \
     -p "{\"spec\": {\"image\": \"$GA_IMAGE\"}}"
    
  3. Update the CatalogSource for the subscription of the operator.

    Note: The ibm-licensing namespace is the default namespace of License Service. If you installed License Service in a custom namespace for your cluster, replace ibm-licensing with your custom namespace.

    licensingNamespace=ibm-licensing
    subName=ibm-licensing-operator-app
    kubectl patch subscription ${subName} -n ${licensingNamespace} --type=merge -p '{"spec": {"source":"ibm-licensing-catalog"}}'
    
  4. Update the subscription channel.

    kubectl patch subscription ${subName} -n ${licensingNamespace} --type=merge -p '{"spec": {"channel":"v4.2"}}'
    

Upgrading License Service by using the OpenShift console

  1. Log in to the OpenShift console.
  2. Update the ibm-licensing-catalog CatalogSource with the latest release version.
    1. Go to Home > Search.
    2. Set the project to All Projects.
    3. For Resources select CatalogSource.
    4. Change the Label filter to Name and filter by ibm-licensing-catalog.
    5. Scroll to the Data section and copy the token by using the Copy to Clipboard option.
  3. Update the subscription channel.
    1. Go to Operators > Installed Operators.
    2. Set the project to All Projects.
    3. Find and select IBM Licensing.
    4. Go to the Subscription tab and click the pencil icon under Update channel.
    5. Select the v4.2 channel and click Save.

Upgrading License Service from version 1.x to 4.x

From License Service version 4.x, ibm-licensing namespace is the recommended namespace to deploy the License Service.

To upgrade from License Service version 1.x to 4.x, you need to complete the following actions:

  • Back up and restore your License Service ConfigMaps.
  • Apply the new CatalogSource.
  • Install the 4.x version of License Service.
  • Delete the ibm-licensing-service-instance deployment of License Service 1.x from the namespace where it was installed.

You do not need to uninstall License Service or delete the IBMLicensing instance of the IBM Licensing operator version 1.x. The installation of the IBM Licensing operator version 4.x detects the existing IBMLicensing instance automatically and manages this instance.

To upgrade from License Service version 1.x to 4.x, complete the following steps:

  1. Log in to the cluster.

  2. Back up and restore the License Service ConfigMaps:

    1. Back up the following ConfigMaps if they are available in the namespace where the License Service version 1.x is installed:

      • ibm-licensing-config
      • ibm-licensing-annotations
      • ibm-licensing-products
      • ibm-licensing-products-vpc-hour
      • ibm-licensing-cloudpaks
      • ibm-licensing-products-groups
      • ibm-licensing-cloudpaks-groups
      • ibm-licensing-cloudpaks-metrics
      • ibm-licensing-products-metrics
      • ibm-licensing-products-metrics-groups
      • ibm-licensing-cloudpaks-metrics-groups
      • ibm-licensing-services

      Run the following command for each ConfigMap that needs to be backed up:

      • For Kubernetes:

        1. Run the following command for each ComfigMap that you need to back up:
        kubectl get cm <the name of the ConfigMap> -o yaml > <the name of the ConfigMap>.yaml
        
        1. Remove the following fields from each ConfigMap backup: .metadata.creationTimestamp, .metadata.resourceVersion, .metadata.uid, .metadata.annotations.kubectl.kubernetes.io/last-applied-configuration, .status.
      • For OpenShift:

        oc extract configmap/<the name of the ConfigMap> --confirm
        
    2. Restore each ConfigMap by running the following command for every ConfigMap:

      • For Kubernetes:

        kubectl apply -f <the name of the ConfigMap>.yaml
        
      • For OpenShift:

        oc create cm <the name of the ConfigMap> --from-file=<the name of the ConfigMap>.yaml --dry-run=client -o yaml | oc apply -f -
        
  3. Apply the ibm-licensing-catalog CatalogSource with the latest release version.

    apiVersion: operators.coreos.com/v1alpha1
    kind: CatalogSource
    metadata:
      name: ibm-licensing-catalog
      namespace: openshift-marketplace
    spec:
      displayName: ibm-licensing
      publisher: IBM
      sourceType: grpc
      image: icr.io/cpopen/ibm-licensing-catalog
      updateStrategy:
        registryPoll:
          interval: 45m
    
  4. Install License Service version 4.x. For more information, see Installing License Service.

  5. Delete the ibm-licensing-service-instance deployment from the namespace of License Service version 1.x.